From 1a038249967b51878bc492df42e24b2af797bb85 Mon Sep 17 00:00:00 2001 From: marha Date: Fri, 21 May 2010 06:36:23 +0000 Subject: xserver git update 21/5/2010 --- xorg-server/hw/xfree86/doc/man/xorg.conf.man.pre | 4868 +++++------ xorg-server/hw/xfree86/doc/sgml/DESIGN.sgml | 7420 ----------------- xorg-server/hw/xfree86/doc/sgml/DESIGN.xml | 9401 ++++++++++++++++++++++ xorg-server/hw/xfree86/doc/sgml/Makefile.am | 85 +- 4 files changed, 11870 insertions(+), 9904 deletions(-) delete mode 100644 xorg-server/hw/xfree86/doc/sgml/DESIGN.sgml create mode 100644 xorg-server/hw/xfree86/doc/sgml/DESIGN.xml (limited to 'xorg-server/hw/xfree86/doc') diff --git a/xorg-server/hw/xfree86/doc/man/xorg.conf.man.pre b/xorg-server/hw/xfree86/doc/man/xorg.conf.man.pre index f7ff6f617..2eb52ae4d 100644 --- a/xorg-server/hw/xfree86/doc/man/xorg.conf.man.pre +++ b/xorg-server/hw/xfree86/doc/man/xorg.conf.man.pre @@ -1,2430 +1,2438 @@ -.\" shorthand for double quote that works everywhere. -.ds q \N'34' -.TH __xconfigfile__ __filemansuffix__ __vendorversion__ -.SH NAME -__xconfigfile__ and __xconfigdir__ \- configuration files for -__xservername__ X server -.SH INTRODUCTION -.B __xservername__ -supports several mechanisms for supplying/obtaining configuration and -run-time parameters: command line options, environment variables, the -__xconfigfile__ and __xconfigdir__ configuration files, auto-detection, -and fallback defaults. When the same information is supplied in more -than one way, the highest precedence mechanism is used. The list of -mechanisms is ordered from highest precedence to lowest. Note that not -all parameters can be supplied via all methods. The available command -line options and environment variables (and some defaults) are -described in the Xserver(__appmansuffix__) and -__xservername__(__appmansuffix__) manual pages. Most configuration file -parameters, with their defaults, are described below. Driver and module -specific configuration parameters are described in the relevant driver -or module manual page. -.SH DESCRIPTION -.B __xservername__ -uses a configuration file called -.I __xconfigfile__ -and files ending in the suffix -.I .conf -from the directory -.I __xconfigdir__ -for its initial setup. -The -.I __xconfigfile__ -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/ -.IR __projectroot__/etc/X11/ -.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__. -.I __projectroot__/etc/X11/__xconfigfile__\-4 -.I __projectroot__/etc/X11/__xconfigfile__ -.IR __projectroot__/lib/X11/__xconfigfile__. -.I __projectroot__/lib/X11/__xconfigfile__\-4 -.I __projectroot__/lib/X11/__xconfigfile__ -.fi -.RE -.PP -where -.I -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 -is the machine's hostname as reported by -.BR gethostname (__libmansuffix__). -.PP -When the __xservername__ server is started by the \(lqroot\(rq user, the config file -search locations are as follows: -.PP -.RS 4 -.nf - -.IR /etc/X11/ -.IR __projectroot__/etc/X11/ -.B $XORGCONFIG -.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__. -.I __projectroot__/etc/X11/__xconfigfile__\-4 -.I __projectroot__/etc/X11/__xconfigfile__ -.IR __projectroot__/lib/X11/__xconfigfile__. -.I __projectroot__/lib/X11/__xconfigfile__\-4 -.I __projectroot__/lib/X11/__xconfigfile__ -.fi -.RE -.PP -where -.I -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 -is the machine's hostname as reported by -.BR gethostname (__libmansuffix__). -.PP -Additional configuration files are searched for in the following -directories when the server is started as a normal user: -.PP -.RS 4 -.nf -.IR /etc/X11/ -.IR __sysconfdir__/X11/ -.I /etc/X11/__xconfigdir__ -.I __sysconfdir__/X11/__xconfigdir__ -.fi -.RE -.PP -where -.I -is a relative path (with no \(lq..\(rq components) specified with the -.B \-configdir -command line option. -.PP -When the __xservername__ server is started by the \(lqroot\(rq user, the -config directory search locations are as follows: -.PP -.RS 4 -.nf - -.IR /etc/X11/ -.IR __sysconfdir__/X11/ -.I /etc/X11/__xconfigdir__ -.I __sysconfdir__/X11/__xconfigdir__ -.fi -.RE -.PP -where -.I -is the path specified with the -.B \-configdir -command line option (which may be absolute or relative). -.PP -Finally, configuration files will also be searched for in directories -reserved for system use. These are to separate configuration files from -the vendor or 3rd party packages from those of local administration. -These files are found in the following directories: -.PP -.RS 4 -.nf -.I /usr/share/X11/__xconfigdir__ -.I __datadir__/X11/__xconfigdir__ -.fi -.RE -.PP -The -.I __xconfigfile__ -and -.I __xconfigdir__ -files are composed of a number of sections which may be present in any order, -or omitted to use default configuration values. -Each section has the form: -.PP -.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 "Extensions " "Extension enabling" -.BR "InputDevice " "Input device description" -.BR "InputClass " "Input class description" -.BR "Device " "Graphics device description" -.BR "VideoAdaptor " "Xv video adaptor description" -.BR "Monitor " "Monitor description" -.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 : [attribute]: pri= -.RE -.PP -where -.I -is an alphanumeric identifier, -.I [attribute] -is an attribute which will be passed to the underlying FPE and -.I -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 / : -.RE -.PP -where -.I -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 -is the hostname of the machine running the font server, and -.I -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 __datadir__/fonts/X11/misc/ -.I __datadir__/fonts/X11/TTF/ -.I __datadir__/fonts/X11/OTF/ -.I __datadir__/fonts/X11/Type1/ -.I __datadir__/fonts/X11/100dpi/ -.I __datadir__/fonts/X11/75dpi/ -.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 default module path is -.PP -.RS 11 -__modulepath__ -.RE -.\" 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__. .log -.RE -.PP -.RS 7 -where -.I -is the display number for the __xservername__ server. -.. -.TP 7 -.BI "XkbDir \*q" path \*q -sets the base directory for keyboard layout files. The -.B \-xkbdir -command line option can be used to override this. The default directory is -.PP -.RS 11 -__xkbdir__ -.RE -.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 \*qUseSIGIO\*q \*q" boolean \*q -This controls whether the __xservername__ server requests that events from -input devices be reported via a SIGIO signal handler (also known as SIGPOLL -on some platforms), or only reported via the standard select(3) loop. -The default behaviour is platform specific. In general you do not want to -use this option unless you are debugging the __xservername__ server, or -working around a specific bug until it is fixed, and understand 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 Terminate_Server -XKB action (usually on Ctrl+Alt+Backspace, depending on XKB options). -This action is normally used to terminate the __xservername__ server. -When this option is enabled, the action has no effect. -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 \*qAllowMouseOpenFail\*q \*q" boolean \*q -This tells the mousedrv(__drivermansuffix__) and vmmouse(__drivermansuffix__) -drivers to not report failure if the mouse device can't be opened/initialised. -It has no effect on the evdev(__drivermansuffix__) or other drivers. -The previous functionality of allowing the server to start up even if -the mouse device can't be opened/initialised is now handled by the -AllowEmptyInput option. -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 \*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: 10 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: 10 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: 10 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. -.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 \*qAIGLX\*q \*q" boolean \*q -enable or disable AIGLX. AIGLX is enabled by default. -.TP 7 -.BI "Option \*qDRI2\*q \*q" boolean \*q -enable or disable DRI2. DRI2 is disabled 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, mouse or vmmouse 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. -.TP 7 -.BI "Option \*qLog\*q \*q" string \*q -This option controls whether the log is flushed and/or synced to disk after -each message. -Possible values are -.B flush -or -.BR sync . -Unset 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 type of modules normally loaded in this section are __xservername__ server -extension 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 DRI extension module can be loaded with the following entry: -.PP -.RS 4 -.B "Load \*qdri\*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, extensions, input, internal, and -multimedia 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 extension modules are available, check the extensions -subdirectory under: -.PP -.RS 4 -.nf -__modulepath__ -.fi -.RE -.PP -The \(lqextmod\(rq, \(lqdbe\(rq, \(lqdri\(rq, \(lqdri2\(rq, \(lqglx\(rq, -and \(lqrecord\(rq extension modules are loaded automatically, if they -are present, unless disabled with \*qDisable\*q entries. -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 "EXTENSIONS SECTION" -The -.B Extensions -section is used to specify which X11 protocol extensions should be enabled -or disabled. -The -.B Extensions -section is optional, as are all of the entries that may be specified in -it. -.PP -Entries in this section are listed as Option statements with the name of -the extension as the first argument, and a boolean value as the second. -The extension name is case\-sensitive, and matches the form shown in the output -of \*qXorg -extension ?\*q. -.PP -.RS 7 -Example: the MIT-SHM extension can be disabled with the following entry: -.PP -.RS 4 -.nf -.B "Section \*qExtensions\*q" -.B " Option \*qMIT-SHM\*q \*qDisable\*q" -.B "EndSection" -.fi -.RE -.RE -.SH "INPUTDEVICE SECTION" -The config file may have multiple -.B InputDevice -sections. -Recent X servers employ input hotplugging to add input devices, with the HAL -backend being the default backend for X servers since 1.4. It is usually not -necessary to provide -.B InputDevice -sections in the xorg.conf if hotplugging is enabled. -.PP -If hotplugging is disabled, there will normally -be at least two: one for the core (primary) keyboard -and one for the core pointer. -If either of these two is missing, a default configuration for the missing -ones will be used. In the absence of an explicitly specified core input -device, the first -.B InputDevice -marked as -.B CorePointer -(or -.BR CoreKeyboard ) -is used. -If there is no match there, the first -.B InputDevice -that uses the \(lqmouse\(rq (or \(lqkbd\(rq) driver is used. -The final fallback is to use built\-in default configurations. -Currently the default configuration may not work as expected on all platforms. -.PP -.B InputDevice -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 evdev (__drivermansuffix__) -on Linux systems, and -.BR kbd (__drivermansuffix__) -and -.BR mousedrv (__drivermansuffix__) -on other platforms. -.PP -.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 \*qAutoServerLayout\*q \*q" boolean \*q -Always add the device to the ServerLayout section used by this instance of -the server. This affects implied layouts as well as explicit layouts -specified in the configuration and/or on the command line. -.TP 7 -.BI "Option \*qCorePointer\*q" -Deprecated, use -.B SendCoreEvents -instead. -.TP 7 -.BI "Option \*qCoreKeyboard\*q" -Deprecated, use -.B SendCoreEvents -instead. -.TP 7 -.BI "Option \*qAlwaysCore\*q \*q" boolean \*q -.B -Deprecated, use -.B SendCoreEvents -instead. -.TP 7 -.BI "Option \*qSendCoreEvents\*q \*q" boolean \*q -Both of these options are equivalent, and when enabled cause the -input device to report core events through the master device. They are -enabled by default. Any device configured to send core events will be -attached to the virtual core pointer or keyboard and control the cursor by -default. Devices with -.B SendCoreEvents -disabled will be \*qfloating\*q and only accessible by clients employing the -X Input extension. This option controls the startup behavior only, a device -may be reattached or set floating at runtime. -.TP 7 -.BI "Option \*qSendDragEvents\*q \*q" boolean \*q -Send core events while dragging. Enabled by default. -.PP -For pointing devices, the following options control how the pointer -is accelerated or decelerated with respect to physical device motion. Most of -these can be adjusted at runtime, see the xinput(1) man page for details. Only -the most important acceleration options are discussed here. -.TP 7 -.BI "Option \*qAccelerationProfile\*q \*q" integer \*q -Select the profile. In layman's terms, the profile constitutes the "feeling" of -the acceleration. More formally, it defines how the transfer function (actual -acceleration as a function of current device velocity and acceleration controls) -is constructed. This is mainly a matter of personal preference. -.PP -.RS 6 -.nf -.B " 0 classic (mostly compatible)" -.B "-1 none (only constant deceleration is applied)" -.B " 1 device-dependent" -.B " 2 polynomial (polynomial function)" -.B " 3 smooth linear (soft knee, then linear)" -.B " 4 simple (normal when slow, otherwise accelerated)" -.B " 5 power (power function)" -.B " 6 linear (more speed, more acceleration)" -.B " 7 limited (like linear, but maxes out at threshold)" -.fi -.RE -.TP 7 -.BI "Option \*qConstantDeceleration\*q \*q" real \*q -Makes the pointer go -.B deceleration -times slower than normal. Most useful for high-resolution devices. -.TP 7 -.BI "Option \*qAdaptiveDeceleration\*q \*q" real \*q -Allows to actually decelerate the pointer when going slow. At most, it will be -.B adaptive deceleration -times slower. Enables precise pointer placement without sacrificing speed. -.TP 7 -.BI "Option \*qAccelerationScheme\*q \*q" string \*q -Selects the scheme, which is the underlying algorithm. -.PP -.RS 7 -.nf -.B "predictable default algorithm (behaving more predictable)" -.B "lightweight old acceleration code (as specified in the X protocol spec)" -.B "none no acceleration or deceleration" -.fi -.RE -.TP 7 -.BI "Option \*qAccelerationNumerator\*q \*q" integer \*q -.TP 7 -.BI "Option \*qAccelerationDenominator\*q \*q" integer \*q -Set numerator and denominator of the acceleration factor. The acceleration -factor is a rational which, together with threshold, can be used to tweak -profiles to suit the users needs. The -.B simple -and -.B limited -profiles use it directly (i.e. they accelerate by the factor), for other -profiles it should hold that a higher acceleration factor leads to a faster -pointer. Typically, 1 is unaccelerated and values up to 5 are sensible. -.TP 7 -.BI "Option \*qAccelerationThreshold\*q \*q" integer \*q -Set the threshold, which is roughly the velocity (usually device units per 10 -ms) required for acceleration to become effective. The precise effect varies -with the profile however. - -.SH "INPUTCLASS SECTION" -The config file may have multiple -.B InputClass -sections. -These sections are optional and are used to provide configuration for a -class of input devices as they are automatically added. An input device can -match more than one -.B InputClass -section. Each class can override settings from a previous class, so it is -best to arrange the sections with the most generic matches first. -.PP -.B InputClass -sections have the following format: -.PP -.RS 4 -.nf -.B "Section \*qInputClass\*q" -.BI " Identifier \*q" name \*q -.I " entries" -.I " ..." -.I " options" -.I " ..." -.B "EndSection" -.fi -.RE -.PP -The -.B Identifier -entry is required in all -.B InputClass -sections. -All other entries are optional. -.PP -The -.B Identifier -entry specifies the unique name for this input class. -The -.B Driver -entry specifies the name of the driver to use for this input device. -After all classes have been examined, the -.RI \*q inputdriver \*q -module from the first -.B Driver -entry will be enabled when using the loadable server. -.PP -When an input device is automatically added, its characteristics are -checked against all -.B InputClass -sections. Each section can contain optional entries to narrow the match -of the class. If none of the optional entries appear, the -.B InputClass -section is generic and will match any input device. If more than one of -these entries appear, they all must match for the configuration to apply. -The allowed matching entries are shown below. -.PP -.TP 7 -.BI "MatchProduct \*q" matchproduct \*q -This entry can be used to check if the substring -.RI \*q matchproduct \*q -occurs in the device's product name. Multiple substrings can be matched by -separating arguments with a '|' character. -.TP 7 -.BI "MatchVendor \*q" matchvendor \*q -This entry can be used to check if the substring -.RI \*q matchvendor \*q -occurs in the device's vendor name. Multiple substrings can be matched by -separating arguments with a '|' character. -.TP 7 -.BI "MatchDevicePath \*q" matchdevice \*q -This entry can be used to check if the device file matches the -.RI \*q matchdevice \*q -pathname pattern. Multiple patterns can be matched by separating arguments -with a '|' character. -.TP 7 -.BI "MatchTag \*q" matchtag \*q -This entry can be used to check if tags assigned by the config backend -matches the -.RI \*q matchtag \*q -pattern. Multiple patterns can be matched by separating arguments -with a '|' character. A match is found if at least one of the tags given in -.RI \*q matchtag \*q -matches at least one of the tags assigned by the backend. -.TP 7 -.BI "MatchIsKeyboard \*q" bool \*q -.TP 7 -.BI "MatchIsPointer \*q" bool \*q -.TP 7 -.BI "MatchIsJoystick \*q" bool \*q -.TP 7 -.BI "MatchIsTablet \*q" bool \*q -.TP 7 -.BI "MatchIsTouchpad \*q" bool \*q -.TP 7 -.BI "MatchIsTouchscreen \*q" bool \*q -Match device types. These entries take a boolean argument similar to -.B Option -entries. -.PP -When an input device has been matched to the -.B InputClass -section, any -.B Option -entries are applied to the device. One -.B InputClass -specific -.B Option -is recognized. See the -.B InputDevice -section above for a description of the remaining -.B Option -entries. -.TP 7 -.BI "Option \*qIgnore\*q \*q" boolean \*q -This optional entry specifies that the device should be ignored entirely, -and not added to the server. This can be useful when the device is handled -by another program and no X events should be generated. -.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 " "\*qPrimary\*q " \*qbool\*q -This optional entry specifies that the monitor should be treated as the primary -monitor. (RandR 1.2-supporting drivers only) -.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 . -.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 imstt (__drivermansuffix__), -.BR intel (__drivermansuffix__), -.BR mga (__drivermansuffix__), -.BR neomagic (__drivermansuffix__), -.BR nv (__drivermansuffix__), -.BR openchrome (__drivermansuffix__), -.BR r128 (__drivermansuffix__), -.BR radeon (__drivermansuffix__), -.BR rendition (__drivermansuffix__), -.BR savage (__drivermansuffix__), -.BR s3virge (__drivermansuffix__), -.BR siliconmotion (__drivermansuffix__), -.BR sis (__drivermansuffix__), -.BR sisusb (__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 vmware (__drivermansuffix__), -.BR voodoo (__drivermansuffix__), -.BR wsfb (__drivermansuffix__), -.BR xgi (__drivermansuffix__), -.BR xgixp (__drivermansuffix__). -.PP -Input drivers: -.BR acecad (__drivermansuffix__), -.BR citron (__drivermansuffix__), -.BR elographics (__drivermansuffix__), -.BR evdev (__drivermansuffix__), -.BR fpit (__drivermansuffix__), -.BR joystick (__drivermansuffix__), -.BR kbd (__drivermansuffix__), -.BR mousedrv (__drivermansuffix__), -.BR mutouch (__drivermansuffix__), -.BR penmount (__drivermansuffix__), -.BR synaptics (__drivermansuffix__), -.BR vmmouse (__drivermansuffix__), -.BR void (__drivermansuffix__), -.BR wacom (__drivermansuffix__). -.PP -Other modules and interfaces: -.BR exa (__drivermansuffix__), -.BR fbdevhw (__drivermansuffix__), -.\" .BR shadowfb (__drivermansuffix__), -.BR v4l (__drivermansuffix__). -.br -.SH AUTHORS -This manual page was largely rewritten by David Dawes -.IR . +.\" shorthand for double quote that works everywhere. +.ds q \N'34' +.TH __xconfigfile__ __filemansuffix__ __vendorversion__ +.SH NAME +__xconfigfile__ and __xconfigdir__ \- configuration files for +__xservername__ X server +.SH INTRODUCTION +.B __xservername__ +supports several mechanisms for supplying/obtaining configuration and +run-time parameters: command line options, environment variables, the +__xconfigfile__ and __xconfigdir__ configuration files, auto-detection, +and fallback defaults. When the same information is supplied in more +than one way, the highest precedence mechanism is used. The list of +mechanisms is ordered from highest precedence to lowest. Note that not +all parameters can be supplied via all methods. The available command +line options and environment variables (and some defaults) are +described in the Xserver(__appmansuffix__) and +__xservername__(__appmansuffix__) manual pages. Most configuration file +parameters, with their defaults, are described below. Driver and module +specific configuration parameters are described in the relevant driver +or module manual page. +.SH DESCRIPTION +.B __xservername__ +uses a configuration file called +.I __xconfigfile__ +and files ending in the suffix +.I .conf +from the directory +.I __xconfigdir__ +for its initial setup. +The +.I __xconfigfile__ +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/ +.IR __projectroot__/etc/X11/ +.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__. +.I __projectroot__/etc/X11/__xconfigfile__\-4 +.I __projectroot__/etc/X11/__xconfigfile__ +.IR __projectroot__/lib/X11/__xconfigfile__. +.I __projectroot__/lib/X11/__xconfigfile__\-4 +.I __projectroot__/lib/X11/__xconfigfile__ +.fi +.RE +.PP +where +.I +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 +is the machine's hostname as reported by +.BR gethostname (__libmansuffix__). +.PP +When the __xservername__ server is started by the \(lqroot\(rq user, the config file +search locations are as follows: +.PP +.RS 4 +.nf + +.IR /etc/X11/ +.IR __projectroot__/etc/X11/ +.B $XORGCONFIG +.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__. +.I __projectroot__/etc/X11/__xconfigfile__\-4 +.I __projectroot__/etc/X11/__xconfigfile__ +.IR __projectroot__/lib/X11/__xconfigfile__. +.I __projectroot__/lib/X11/__xconfigfile__\-4 +.I __projectroot__/lib/X11/__xconfigfile__ +.fi +.RE +.PP +where +.I +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 +is the machine's hostname as reported by +.BR gethostname (__libmansuffix__). +.PP +Additional configuration files are searched for in the following +directories when the server is started as a normal user: +.PP +.RS 4 +.nf +.IR /etc/X11/ +.IR __sysconfdir__/X11/ +.I /etc/X11/__xconfigdir__ +.I __sysconfdir__/X11/__xconfigdir__ +.fi +.RE +.PP +where +.I +is a relative path (with no \(lq..\(rq components) specified with the +.B \-configdir +command line option. +.PP +When the __xservername__ server is started by the \(lqroot\(rq user, the +config directory search locations are as follows: +.PP +.RS 4 +.nf + +.IR /etc/X11/ +.IR __sysconfdir__/X11/ +.I /etc/X11/__xconfigdir__ +.I __sysconfdir__/X11/__xconfigdir__ +.fi +.RE +.PP +where +.I +is the path specified with the +.B \-configdir +command line option (which may be absolute or relative). +.PP +Finally, configuration files will also be searched for in directories +reserved for system use. These are to separate configuration files from +the vendor or 3rd party packages from those of local administration. +These files are found in the following directories: +.PP +.RS 4 +.nf +.I /usr/share/X11/__xconfigdir__ +.I __datadir__/X11/__xconfigdir__ +.fi +.RE +.PP +The +.I __xconfigfile__ +and +.I __xconfigdir__ +files are composed of a number of sections which may be present in any order, +or omitted to use default configuration values. +Each section has the form: +.PP +.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 "Extensions " "Extension enabling" +.BR "InputDevice " "Input device description" +.BR "InputClass " "Input class description" +.BR "Device " "Graphics device description" +.BR "VideoAdaptor " "Xv video adaptor description" +.BR "Monitor " "Monitor description" +.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 : [attribute]: pri= +.RE +.PP +where +.I +is an alphanumeric identifier, +.I [attribute] +is an attribute which will be passed to the underlying FPE and +.I +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 / : +.RE +.PP +where +.I +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 +is the hostname of the machine running the font server, and +.I +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 __datadir__/fonts/X11/misc/ +.I __datadir__/fonts/X11/TTF/ +.I __datadir__/fonts/X11/OTF/ +.I __datadir__/fonts/X11/Type1/ +.I __datadir__/fonts/X11/100dpi/ +.I __datadir__/fonts/X11/75dpi/ +.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 default module path is +.PP +.RS 11 +__modulepath__ +.RE +.\" 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__. .log +.RE +.PP +.RS 7 +where +.I +is the display number for the __xservername__ server. +.. +.TP 7 +.BI "XkbDir \*q" path \*q +sets the base directory for keyboard layout files. The +.B \-xkbdir +command line option can be used to override this. The default directory is +.PP +.RS 11 +__xkbdir__ +.RE +.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 \*qUseSIGIO\*q \*q" boolean \*q +This controls whether the __xservername__ server requests that events from +input devices be reported via a SIGIO signal handler (also known as SIGPOLL +on some platforms), or only reported via the standard select(3) loop. +The default behaviour is platform specific. In general you do not want to +use this option unless you are debugging the __xservername__ server, or +working around a specific bug until it is fixed, and understand 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 Terminate_Server +XKB action (usually on Ctrl+Alt+Backspace, depending on XKB options). +This action is normally used to terminate the __xservername__ server. +When this option is enabled, the action has no effect. +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 \*qAllowMouseOpenFail\*q \*q" boolean \*q +This tells the mousedrv(__drivermansuffix__) and vmmouse(__drivermansuffix__) +drivers to not report failure if the mouse device can't be opened/initialised. +It has no effect on the evdev(__drivermansuffix__) or other drivers. +The previous functionality of allowing the server to start up even if +the mouse device can't be opened/initialised is now handled by the +AllowEmptyInput option. +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 \*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: 10 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: 10 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: 10 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. +.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 \*qAIGLX\*q \*q" boolean \*q +enable or disable AIGLX. AIGLX is enabled by default. +.TP 7 +.BI "Option \*qDRI2\*q \*q" boolean \*q +enable or disable DRI2. DRI2 is disabled 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, mouse or vmmouse 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. +.TP 7 +.BI "Option \*qLog\*q \*q" string \*q +This option controls whether the log is flushed and/or synced to disk after +each message. +Possible values are +.B flush +or +.BR sync . +Unset 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 type of modules normally loaded in this section are __xservername__ server +extension 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 DRI extension module can be loaded with the following entry: +.PP +.RS 4 +.B "Load \*qdri\*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, extensions, input, internal, and +multimedia 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 extension modules are available, check the extensions +subdirectory under: +.PP +.RS 4 +.nf +__modulepath__ +.fi +.RE +.PP +The \(lqextmod\(rq, \(lqdbe\(rq, \(lqdri\(rq, \(lqdri2\(rq, \(lqglx\(rq, +and \(lqrecord\(rq extension modules are loaded automatically, if they +are present, unless disabled with \*qDisable\*q entries. +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 "EXTENSIONS SECTION" +The +.B Extensions +section is used to specify which X11 protocol extensions should be enabled +or disabled. +The +.B Extensions +section is optional, as are all of the entries that may be specified in +it. +.PP +Entries in this section are listed as Option statements with the name of +the extension as the first argument, and a boolean value as the second. +The extension name is case\-sensitive, and matches the form shown in the output +of \*qXorg -extension ?\*q. +.PP +.RS 7 +Example: the MIT-SHM extension can be disabled with the following entry: +.PP +.RS 4 +.nf +.B "Section \*qExtensions\*q" +.B " Option \*qMIT-SHM\*q \*qDisable\*q" +.B "EndSection" +.fi +.RE +.RE +.SH "INPUTDEVICE SECTION" +The config file may have multiple +.B InputDevice +sections. +Recent X servers employ input hotplugging to add input devices, with the HAL +backend being the default backend for X servers since 1.4. It is usually not +necessary to provide +.B InputDevice +sections in the xorg.conf if hotplugging is enabled. +.PP +If hotplugging is disabled, there will normally +be at least two: one for the core (primary) keyboard +and one for the core pointer. +If either of these two is missing, a default configuration for the missing +ones will be used. In the absence of an explicitly specified core input +device, the first +.B InputDevice +marked as +.B CorePointer +(or +.BR CoreKeyboard ) +is used. +If there is no match there, the first +.B InputDevice +that uses the \(lqmouse\(rq (or \(lqkbd\(rq) driver is used. +The final fallback is to use built\-in default configurations. +Currently the default configuration may not work as expected on all platforms. +.PP +.B InputDevice +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 evdev (__drivermansuffix__) +on Linux systems, and +.BR kbd (__drivermansuffix__) +and +.BR mousedrv (__drivermansuffix__) +on other platforms. +.PP +.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 \*qAutoServerLayout\*q \*q" boolean \*q +Always add the device to the ServerLayout section used by this instance of +the server. This affects implied layouts as well as explicit layouts +specified in the configuration and/or on the command line. +.TP 7 +.BI "Option \*qCorePointer\*q" +Deprecated, use +.B SendCoreEvents +instead. +.TP 7 +.BI "Option \*qCoreKeyboard\*q" +Deprecated, use +.B SendCoreEvents +instead. +.TP 7 +.BI "Option \*qAlwaysCore\*q \*q" boolean \*q +.B +Deprecated, use +.B SendCoreEvents +instead. +.TP 7 +.BI "Option \*qSendCoreEvents\*q \*q" boolean \*q +Both of these options are equivalent, and when enabled cause the +input device to report core events through the master device. They are +enabled by default. Any device configured to send core events will be +attached to the virtual core pointer or keyboard and control the cursor by +default. Devices with +.B SendCoreEvents +disabled will be \*qfloating\*q and only accessible by clients employing the +X Input extension. This option controls the startup behavior only, a device +may be reattached or set floating at runtime. +.TP 7 +.BI "Option \*qSendDragEvents\*q \*q" boolean \*q +Send core events while dragging. Enabled by default. +.PP +For pointing devices, the following options control how the pointer +is accelerated or decelerated with respect to physical device motion. Most of +these can be adjusted at runtime, see the xinput(1) man page for details. Only +the most important acceleration options are discussed here. +.TP 7 +.BI "Option \*qAccelerationProfile\*q \*q" integer \*q +Select the profile. In layman's terms, the profile constitutes the "feeling" of +the acceleration. More formally, it defines how the transfer function (actual +acceleration as a function of current device velocity and acceleration controls) +is constructed. This is mainly a matter of personal preference. +.PP +.RS 6 +.nf +.B " 0 classic (mostly compatible)" +.B "-1 none (only constant deceleration is applied)" +.B " 1 device-dependent" +.B " 2 polynomial (polynomial function)" +.B " 3 smooth linear (soft knee, then linear)" +.B " 4 simple (normal when slow, otherwise accelerated)" +.B " 5 power (power function)" +.B " 6 linear (more speed, more acceleration)" +.B " 7 limited (like linear, but maxes out at threshold)" +.fi +.RE +.TP 7 +.BI "Option \*qConstantDeceleration\*q \*q" real \*q +Makes the pointer go +.B deceleration +times slower than normal. Most useful for high-resolution devices. +.TP 7 +.BI "Option \*qAdaptiveDeceleration\*q \*q" real \*q +Allows to actually decelerate the pointer when going slow. At most, it will be +.B adaptive deceleration +times slower. Enables precise pointer placement without sacrificing speed. +.TP 7 +.BI "Option \*qAccelerationScheme\*q \*q" string \*q +Selects the scheme, which is the underlying algorithm. +.PP +.RS 7 +.nf +.B "predictable default algorithm (behaving more predictable)" +.B "lightweight old acceleration code (as specified in the X protocol spec)" +.B "none no acceleration or deceleration" +.fi +.RE +.TP 7 +.BI "Option \*qAccelerationNumerator\*q \*q" integer \*q +.TP 7 +.BI "Option \*qAccelerationDenominator\*q \*q" integer \*q +Set numerator and denominator of the acceleration factor. The acceleration +factor is a rational which, together with threshold, can be used to tweak +profiles to suit the users needs. The +.B simple +and +.B limited +profiles use it directly (i.e. they accelerate by the factor), for other +profiles it should hold that a higher acceleration factor leads to a faster +pointer. Typically, 1 is unaccelerated and values up to 5 are sensible. +.TP 7 +.BI "Option \*qAccelerationThreshold\*q \*q" integer \*q +Set the threshold, which is roughly the velocity (usually device units per 10 +ms) required for acceleration to become effective. The precise effect varies +with the profile however. + +.SH "INPUTCLASS SECTION" +The config file may have multiple +.B InputClass +sections. +These sections are optional and are used to provide configuration for a +class of input devices as they are automatically added. An input device can +match more than one +.B InputClass +section. Each class can override settings from a previous class, so it is +best to arrange the sections with the most generic matches first. +.PP +.B InputClass +sections have the following format: +.PP +.RS 4 +.nf +.B "Section \*qInputClass\*q" +.BI " Identifier \*q" name \*q +.I " entries" +.I " ..." +.I " options" +.I " ..." +.B "EndSection" +.fi +.RE +.PP +The +.B Identifier +entry is required in all +.B InputClass +sections. +All other entries are optional. +.PP +The +.B Identifier +entry specifies the unique name for this input class. +The +.B Driver +entry specifies the name of the driver to use for this input device. +After all classes have been examined, the +.RI \*q inputdriver \*q +module from the first +.B Driver +entry will be enabled when using the loadable server. +.PP +When an input device is automatically added, its characteristics are +checked against all +.B InputClass +sections. Each section can contain optional entries to narrow the match +of the class. If none of the optional entries appear, the +.B InputClass +section is generic and will match any input device. If more than one of +these entries appear, they all must match for the configuration to apply. +The allowed matching entries are shown below. +.PP +.TP 7 +.BI "MatchProduct \*q" matchproduct \*q +This entry can be used to check if the substring +.RI \*q matchproduct \*q +occurs in the device's product name. Multiple substrings can be matched by +separating arguments with a '|' character. +.TP 7 +.BI "MatchVendor \*q" matchvendor \*q +This entry can be used to check if the substring +.RI \*q matchvendor \*q +occurs in the device's vendor name. Multiple substrings can be matched by +separating arguments with a '|' character. +.TP 7 +.BI "MatchDevicePath \*q" matchdevice \*q +This entry can be used to check if the device file matches the +.RI \*q matchdevice \*q +pathname pattern. Multiple patterns can be matched by separating arguments +with a '|' character. +.TP 7 +.BI "MatchTag \*q" matchtag \*q +This entry can be used to check if tags assigned by the config backend +matches the +.RI \*q matchtag \*q +pattern. Multiple patterns can be matched by separating arguments +with a '|' character. A match is found if at least one of the tags given in +.RI \*q matchtag \*q +matches at least one of the tags assigned by the backend. +.TP 7 +.BI "MatchIsKeyboard \*q" bool \*q +.TP 7 +.BI "MatchIsPointer \*q" bool \*q +.TP 7 +.BI "MatchIsJoystick \*q" bool \*q +.TP 7 +.BI "MatchIsTablet \*q" bool \*q +.TP 7 +.BI "MatchIsTouchpad \*q" bool \*q +.TP 7 +.BI "MatchIsTouchscreen \*q" bool \*q +Match device types. These entries take a boolean argument similar to +.B Option +entries. +.PP +When an input device has been matched to the +.B InputClass +section, any +.B Option +entries are applied to the device. One +.B InputClass +specific +.B Option +is recognized. See the +.B InputDevice +section above for a description of the remaining +.B Option +entries. +.TP 7 +.BI "Option \*qIgnore\*q \*q" boolean \*q +This optional entry specifies that the device should be ignored entirely, +and not added to the server. This can be useful when the device is handled +by another program and no X events should be generated. +.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 " "\*qPrimary\*q " \*qbool\*q +This optional entry specifies that the monitor should be treated as the primary +monitor. (RandR 1.2-supporting drivers only) +.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 " "\*qDefaultModes\*q " \*qbool\*q +This optional entry specifies whether the server should add supported default +modes to the list of modes offered on this monitor. By default, the server +will add default modes; you should only disable this if you can guarantee +that EDID will be available at all times, or if you have added custom modelines +which the server can use. +(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 . +.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 imstt (__drivermansuffix__), +.BR intel (__drivermansuffix__), +.BR mga (__drivermansuffix__), +.BR neomagic (__drivermansuffix__), +.BR nv (__drivermansuffix__), +.BR openchrome (__drivermansuffix__), +.BR r128 (__drivermansuffix__), +.BR radeon (__drivermansuffix__), +.BR rendition (__drivermansuffix__), +.BR savage (__drivermansuffix__), +.BR s3virge (__drivermansuffix__), +.BR siliconmotion (__drivermansuffix__), +.BR sis (__drivermansuffix__), +.BR sisusb (__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 vmware (__drivermansuffix__), +.BR voodoo (__drivermansuffix__), +.BR wsfb (__drivermansuffix__), +.BR xgi (__drivermansuffix__), +.BR xgixp (__drivermansuffix__). +.PP +Input drivers: +.BR acecad (__drivermansuffix__), +.BR citron (__drivermansuffix__), +.BR elographics (__drivermansuffix__), +.BR evdev (__drivermansuffix__), +.BR fpit (__drivermansuffix__), +.BR joystick (__drivermansuffix__), +.BR kbd (__drivermansuffix__), +.BR mousedrv (__drivermansuffix__), +.BR mutouch (__drivermansuffix__), +.BR penmount (__drivermansuffix__), +.BR synaptics (__drivermansuffix__), +.BR vmmouse (__drivermansuffix__), +.BR void (__drivermansuffix__), +.BR wacom (__drivermansuffix__). +.PP +Other modules and interfaces: +.BR exa (__drivermansuffix__), +.BR fbdevhw (__drivermansuffix__), +.\" .BR shadowfb (__drivermansuffix__), +.BR v4l (__drivermansuffix__). +.br +.SH AUTHORS +This manual page was largely rewritten by David Dawes +.IR . diff --git a/xorg-server/hw/xfree86/doc/sgml/DESIGN.sgml b/xorg-server/hw/xfree86/doc/sgml/DESIGN.sgml deleted file mode 100644 index c6fc63edb..000000000 --- a/xorg-server/hw/xfree86/doc/sgml/DESIGN.sgml +++ /dev/null @@ -1,7420 +0,0 @@ - %defs; - - - - - - - - - - - - - - - - - - - - - - -] > - -
- -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_PERCENT, - 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. - - &s.code;OPTV_PERCENT&e.code; can be used for option values that are - specified in percent (e.g. "20%"). These values are a floating point - number with a percent sign appended. If the percent sign is missing, - the parser will fail to match the value. - - 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/DESIGN.xml b/xorg-server/hw/xfree86/doc/sgml/DESIGN.xml new file mode 100644 index 000000000..ff132a182 --- /dev/null +++ b/xorg-server/hw/xfree86/doc/sgml/DESIGN.xml @@ -0,0 +1,9401 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ + <!ENTITY % defs SYSTEM "/xserver/doc/xml/xserver.ent"> %defs; + <!-- config file keyword markup --> + <!-- specific config file keywords --> + <!ENTITY k.device "<emphasis>Device</emphasis>"> + <!ENTITY k.monitor "<emphasis>Monitor</emphasis>"> + <!ENTITY k.display "<emphasis>Display</emphasis>"> + <!ENTITY k.inputdevice "<emphasis>InputDevice</emphasis>"> + <!ENTITY k.screen "<emphasis>Screen</emphasis>"> + <!ENTITY k.serverlayout "<emphasis>ServerLayout</emphasis>"> + <!ENTITY k.driver "<emphasis>Driver</emphasis>"> + <!ENTITY k.module "<emphasis>Module</emphasis>"> + <!ENTITY k.identifier "<emphasis>Identifier</emphasis>"> + <!ENTITY k.serverflags "<emphasis>ServerFlags</emphasis>"> +] > + +<article> + <articleinfo> + + <title>XFree86 DDX Design (Xorg server version &xserver.version;) + + + + The XFree86 Project, Inc. + + The X.Org Foundation, Inc. + + + JimGettys + Updates for X11R6.7 + + + + &xserver.reldate; + Xorg server version &xserver.version; + + + + +This document describes software undergoing continual evolution, and +the interfaces described here are subject to change without notice. +This document is intended to cover the interfaces as found in the +xorg-server-&xserver.version; release, but is probably not completely +in sync with the code base. + + + + + Preface + + +This document was originally the design spec for the DDX layer of the +XFree86 4.0 X server. The X.Org Foundation adopted the XFree86 4.4rc2 +version of that server as the basis of the Xorg server project, and has +evolved the XFree86 DDX layer greatly since forking. This document thus +covers only the current implementation of the XFree86 DDX as found in the +Xorg server &xserver.version; release, and no longer matches the XFree86 +server itself. + + + +The XFree86 Project's broad design principles for XFree86 4.0 were: + + keep it reasonable + + We cannot rewrite the complete server + + We don't want to re-invent the wheel + + + keep it modular + + As many things as possible should go into modules + + The basic loader binary should be minimal + + A clean design with well defined layering is + important + DDX specific global variables are a nono + + The structure should be flexible enough to allow + future extensions + The structure should minimize duplication of + common code + + keep important features in mind + + multiple screens, including multiple instances + of drivers + mixing different color depths and visuals on + different and ideally even on the same screen + + better control of the PCI device used + + better config file parser + get rid of all VGA compatibility assumptions + + + + + + +While the XFree86 project had a goal of avoiding changes to the DIX +layer unless they found major deficiencies there, to avoid divergence from +the X.Org sample implementation they were integrating changes from, the +X.Org developers now maintain both sides, and make changes where they are +most appropriate. This document concentrates on the XFree86 DDX layer used +in the Xorg server itself (the code found in hw/xfree86 +in the source tree), and developers will also want to refer to the +Xserver-spec documentation that covers the DIX layer +routines common to all the X servers in the sample implementation. + + + + + The xorg.conf File + + +The xorg.conf file format is similar to the old format, with the following +changes: + + + + &k.device; section + + + 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: + + + + Driver "drivername" + + Specifies the name of the driver to be used for the card. This + is mandatory. + + BusID "busslot" + + 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". + + + + + + A &k.device; section is considered active if there is a reference + to it in an active &k.screen; section. + + + + + &k.screen; section + + + 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. + + + + + &k.inputdevice; section + + + The &k.inputdevice; section is a new section that describes + configuration information for input devices. It replaces the old + Keyboard, Pointer and XInput + sections. Like the &k.device; section, it has two mandatory keywords: + &k.identifier; and &k.driver;. For compatibility purposes the old + Keyboard and Pointer sections are + converted by the parser into &k.inputdevice; sections as follows: + + + Keyboard + + &k.identifier; "Implicit Core Keyboard" + &k.driver; "keyboard" + + Pointer + + &k.identifier; "Implicit Core Pointer" + &k.driver; "mouse" + + + + + + 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 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. + + + + + &k.serverlayout; section + + + 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: + + + Section "ServerLayout" + Identifier "Main Layout" + Screen 0 "Screen 1" "" "" "" "Screen 2" + Screen 1 "Screen 2" + Screen "Screen 3" + EndSection + + + + + 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 Absolute keyword. If the coordinates are + omitted, a value of (0,0) is assumed. An example + of absolute positioning follows: + + + 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 + + + + + In the relative case, the position is specified by either using one of + the following keywords followed by the name of the reference screen: + + + RightOf + LeftOf + Above + Below + Relative + + + + + When the Relative 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. + + + 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 + + + + + + Options + + + 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 Options section + for details. + + + + + + Driver Interface + + +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: + + + ScreenInit + + + An initialisation function is called from the DIX layer for each + screen at the start of each server generation. + + + Enter VT + + + The server takes control of the console. + + + Leave VT + + + The server releases control of the console. + + + Mode Switch + + + Change video mode. + + + ViewPort change + + + Change the origin of the physical view port. + + + ScreenSaver state change + + + Screen saver activation/deactivation. + + + CloseScreen + + + A close screen function is called from the DIX layer for each screen + at the end of each server generation. + + + + + + +In addition to these events, the following functions are required by +the XFree86 common layer: + + + Identify + + + Print a driver identifying message. + + + Probe + + + This is how a driver identifies if there is any hardware present that + it knows how to drive. + + + PreInit + + + Process information from the xorg.conf file, determine the + full characteristics of the hardware, and determine if a valid + configuration is present. + + + + + +The VidMode extension also requires: + + + ValidMode + + + 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. + + + + + + +Other extensions may require other entry points. The drivers will +inform the common layer of these in such cases. + + + + + Resource Access Control Introduction + + +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. + + + + Terms and Definitions + + + 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, 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. + + + + + 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. + + + + + 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. + + + + 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: + + address & mask == base + + and + + base & mask == base + + Resources addressed in such a way are called sparse resources. + + + + + + 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 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. + + + + + + + Control Flow in the Server and Mandatory Driver Functions + + +At the start of each server generation, main() +(dix/main.c) calls the DDX function +InitOutput(). This is the first place that the DDX gets +control. InitOutput() is expected to fill in the global +screenInfo struct, and one +screenInfo.screen[] entry for each screen present. +Here is what InitOutput() does: + + + + Parse the xorg.conf file + + + 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. + + + + + + Initial processing of parsed information and command line options + + + + This is done at the start of the first server generation only. + + + + The initial processing is to determine paths like the + ModulePath, etc, and to determine which &k.serverlayout;, + &k.screen; and &k.device; sections are active. + + + + + + Enable port I/O access + + + 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. + + + + + + General bus probe + + + 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 xf86GetPciVideoInfo(). + + +
+ + pciVideoPtr *xf86GetPciVideoInfo(void); + +
+ returns a pointer to a list of pointers to + pciVideoRec entries, of which there is one for + each detected PCI video card. The list is terminated with a + NULL pointer. If no PCI video cards were + detected, the return value is NULL. + +
+
+ + + After the bus probe, the resource broker is initialised. + + + + + + Load initial set of modules + + + 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. + + + + + + Register Video and Input Drivers + + + This is done at the start of the first server generation only. + + + + When a driver module is loaded, the loader calls its + Setup function. For video drivers, this function + calls xf86AddDriver() to register the driver's + DriverRec, which contains a small set of essential + details and driver entry points required during the early phase of + InitOutput(). xf86AddDriver() + adds it to the global xf86DriverList[] array. + + + + The DriverRec contains the driver canonical name, + the Identify(), + Probe() and AvailableOptions() + 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 + ScrnInfoRec. + + + + For a static server, the xf86DriverList[] 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 + Setup function calls + xf86AddInputDriver() to register the driver's + InputDriverRec, which contains a small set of + essential details and driver entry points required during the early + phase of InitInput(). + xf86AddInputDriver() adds it to the global + xf86InputDriverList[] array. For a static server, + the xf86InputDriverList[] array is initialised at + build time. + + + + Both the xf86DriverList[] and + xf86InputDriverList[] arrays have been initialised + by the end of this stage. + + + + Once all the drivers are registered, their + ChipIdentify() functions are called. + + +
+ + void ChipIdentify(int flags); + +
+ 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. +
+
+ +
+ + void xf86PrintChipsets(const char *drvname, const char *drvmsg, + SymTabPtr chips); + +
+ This function provides an easy way for a driver's ChipIdentify + function to format the identification message. +
+
+ + + + Initialise Access Control + + + 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. + + + + + + Video Driver Probe + + + This is done at the start of the first server generation only. The + ChipProbe() function of each registered video driver + is called. + + +
+ + Bool ChipProbe(DriverPtr drv, int flags); + +
+ The purpose of this is to identify all instances of hardware + supported by the driver. The flags value is currently either 0, + PROBE_DEFAULT or PROBE_DETECT. + PROBE_DETECT is used if "-configure" or "-probe" + command line arguments are given and indicates to the + Probe() 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 xf86MatchDevice(). The number + of matches found limits the maximum number of instances for this + driver. If no matches are found, the function should return + FALSE 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 + xf86MatchPciInstances() helper function be used + for identifying matching PCI devices, and similarly the + xf86MatchIsaInstances() for ISA (non-PCI) devices + (see the RAC section). These helpers also + checks and claims the appropriate entity. When not using the + helper, that should be done with xf86CheckPciSlot() + and xf86ClaimPciSlot() for PCI devices and + xf86ClaimIsaSlot() for ISA devices (see the + 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 xf86ConfigPciEntity() helper function + for PCI and xf86ConfigIsaEntity() for ISA + (see the RAC section). It is possible to + register some entity specific functions with those helpers. When + not using the helpers, the xf86AddEntityToScreen() + xf86ClaimFixedResources() and + xf86SetEntityFuncs() should be used instead (see + the 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 FALSE 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 FALSE. + + + + Allocate a ScrnInfoRec 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 + xf86ConfigIsaEntity() helper function for ISA + instances or xf86ConfigPciEntity() for PCI instances. + These functions allocate a ScrnInfoRec for active + entities. Optionally xf86AllocateScreen() + function may also be used to allocate the ScrnInfoRec. + 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 TRUE if one or more instances are found, + and FALSE otherwise. + + +
+ +
+ + int xf86MatchDevice(const char *drivername, + GDevPtr **driversectlist) + +
+ This function takes the name of the driver and returns via + driversectlist 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 -1. + + + + The caller should use xfree() to free + *driversectlist when it is no longer needed. + + +
+ +
+ + ScrnInfoPtr xf86AllocateScreen(DriverPtr drv, int flags) + +
+ This function allocates a new ScrnInfoRec in the + xf86Screens[] array. This function is normally + called by the video driver ChipProbe() functions. + The return value is a pointer to the newly allocated + ScrnInfoRec. The scrnIndex, + origIndex, module and + drv fields are initialised. The reference count + in drv is incremented. The storage for any + currently allocated privates pointers is also allocated and + the privates 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. +
+
+ + + At the completion of this, a list of ScrnInfoRecs + have been allocated in the xf86Screens[] array, and + the associated entities and fixed resources have been claimed. The + following ScrnInfoRec fields must be initialised at + this point: + + + driverVersion + driverName + scrnIndex(*) + origIndex(*) + drv(*) + module(*) + name + Probe + PreInit + ScreenInit + EnterVT + LeaveVT + numEntities + entityList + access + + + (*) These are initialised when the ScrnInfoRec + is allocated, and not explicitly by the driver. + + + + The following ScrnInfoRec fields must be initialised + if the driver is going to use them: + + + SwitchMode + AdjustFrame + FreeScreen + ValidMode + + + + + + Matching Screens + + + This is done at the start of the first server generation only. + + + + After the Probe phase is finished, there will be some number of + ScrnInfoRecs. 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, InitOutput() sets + screenInfo.numScreens to 0 and + returns. + + + + At this point the following fields of the ScrnInfoRecs + must be initialised: + + + confScreen + + + + + + + Allocate non-conflicting resources + + + 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 EntityInit() function + during the Probe phase, then they are called here. + + + + + + Sort the Screens and pre-check Monitor Information + + + 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. + + + + + + PreInit + + + This is done at the start of the first server generation only. + + + + For each ScrnInfoRec, enable access to the screens entities and call + the ChipPreInit() function. + + +
+ + Bool ChipPreInit(ScrnInfoRec screen, int flags); + +
+ 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 ScrnInfoRec 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 + xf86GetEntityInfo()) 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 EntityInit() 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 ScrnInfoRec's driverPrivate + 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 + xf86AllocateScrnInfoPrivateIndex(). 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 + xf86RegisterResources(). 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 + xf86SetOperatingState(). + + + + 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 xf86LoadSubModule() + or the xf86LoadDrvSubModule() function should be + used to load modules depending on whether a + ScrnInfoRec has been set up. A driver may unload + a module within this function if it was only needed temporarily, + and the xf86UnloadSubModule() 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 ScrnInfoRec fields should be filled + out in this function. + + + + ChipPreInit() returns FALSE when + the configuration is unusable in some way (unsupported depth, no + valid modes, not enough video memory, etc), and TRUE + if it is usable. + + + + It is expected that if the ChipPreInit() function + returns TRUE, 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 ChipPreInit() function. +
+
+ + + The ScrnInfoRecs for screens where the ChipPreInit() fails are removed. + If none remain, InitOutput() sets screenInfo.numScreens to 0 and returns. + + + + At this point, further fields of the ScrnInfoRecs 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 ScrnInfoRecs should be filled in if the + driver is going to use them: + + + 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 + + + +
+ + pointer xf86LoadSubModule(ScrnInfoPtr pScrn, const char *name); + and + pointer xf86LoadDrvSubModule(DriverPtr drv, const char *name); + +
+ Load a module that a driver depends on. This function loads the + module name 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 NULL. If a driver + needs to explicitly unload a module it has loaded in this way, + the return value must be saved and passed to + xf86UnloadSubModule() when unloading. + +
+
+ +
+ + void xf86UnloadSubModule(pointer module); + +
+ Unloads the module referenced by module. + module should be a pointer returned previously + by xf86LoadSubModule() or + xf86LoadDrvSubModule() . + +
+
+ + + + Cleaning up Unused Drivers + + + 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. + + + + + + Consistency Checks + + + 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. + + + + + + Check if Resource Control is Needed + + + 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. + + + + + AddScreen (ScreenInit) + + + At this point, the valid screens are known. + AddScreen() is called for each of them, passing + ChipScreenInit() as the argument. + AddScreen() is a DIX function that allocates a new + screenInfo.screen[] entry (aka + pScreen), and does some basic initialisation of it. + It then calls the ChipScreenInit() function, with + pScreen as one of its arguments. If + ChipScreenInit() returns FALSE, + AddScreen() returns -1. Otherwise + it returns the index of the screen. AddScreen() + should only fail because of programming errors or failure to allocate + resources (like memory). All configuration problems should be + detected BEFORE this point. + + +
+ + Bool ChipScreenInit(int index, ScreenPtr pScreen, + int argc, char **argv); + +
+ This is called at the start of each server generation. + + + + Fill in all of pScreen, 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 + (RAC_FB), the pointer operations + (RAC_CURSOR), the viewport change operations + (RAC_VIEWPORT) and the colormap operations + (RAC_COLORMAP). 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 racMemFlags and + racIoFlags fields of the ScrnInfoRec + 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 ScrnInfoRec's + vtSema field should be set to TRUE + just prior to changing the video hardware's state. + +
+
+ + + + The ChipScreenInit() function (or functions from other + layers that it calls) should allocate entries in the + ScreenRec's devPrivates area by + calling AllocateScreenPrivateIndex() if it needs + per-generation storage. Since the ScreenRec's + devPrivates information is cleared for each server + generation, this is the correct place to initialise it. + + + + After AddScreen() has successfully returned, the + following ScrnInfoRec fields are initialised: + + + pScreen + racMemFlags + racIoFlags + + + + + The ChipScreenInit() function should initialise the + CloseScreen and SaveScreen fields + of pScreen. The old value of + pScreen->CloseScreen should be saved as part of + the driver's per-screen private data, allowing it to be called from + ChipCloseScreen(). This means that the existing + CloseScreen() function is wrapped. + + + + + Finalising RAC Initialisation + + + After all the ChipScreenInit() 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: + + + + 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). + + + + A resource marked disabled during OPERATING state will be + ignored entirely. + + + + 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. + + + + 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. + + + + + + + + Finishing InitOutput() + + + At this point InitOutput() is finished, and all the + screens have been setup in their initial video mode. + + + + + + Mode Switching + + + When a SwitchMode event is received, ChipSwitchMode() + is called (when it exists): + + +
+ + Bool ChipSwitchMode(int index, DisplayModePtr mode, int flags); + +
+ Initialises the new mode for the screen identified by + index;. The viewport may need to be adjusted + also. + +
+
+ + + + + Changing Viewport + + + When a Change Viewport event is received, + ChipAdjustFrame() is called (when it exists): + + +
+ + void ChipAdjustFrame(int index, int x, int y, int flags); + +
+ Changes the viewport for the screen identified by + index;. + + + + 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 + frameX0, frameY0, frameX1 + and frameY1 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. + +
+
+ + + + + VT Switching + + + When a VT switch event is received, xf86VTSwitch() + is called. xf86VTSwitch() does the following: + + + On ENTER: + + + + enable port I/O access + + + + save and initialise the bus/resource state + + + + enter the SETUP server state + + + + calls ChipEnterVT() for each screen + + + + enter the OPERATING server state + + + + validate GCs + + + + Restore fb from saved pixmap for each screen + + + + Enable all input devices + + + + + + On LEAVE: + + + + Save fb to pixmap for each screen + + + + validate GCs + + + + enter the SETUP server state + + + + calls ChipLeaveVT() for each screen + + + + disable all input devices + + + + restore bus/resource state + + + + disables port I/O access + + + + + + + +
+ + Bool ChipEnterVT(int index, int flags); + +
+ 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? + + +
+ +
+ + void ChipLeaveVT(int index, int flags); + +
+ This function should restore the saved video state. If + appropriate it should also turn off the HW cursor, and invalidate + any pixmap/font caches. + + +
+ + + Optionally, ChipLeaveVT() may also unmap memory + regions. If so, ChipEnterVT() will need to remap + them. Additionally, if an aperture used to access video memory is + unmapped and remapped in this fashion, ChipEnterVT() + 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 + ModifyPixmapHeader() function, as follows + + +
+ + (*pScreen->ModifyPixmapHeader)(pScrn->ppix, + -1, -1, -1, -1, -1, NewApertureAddress); + +
+ where the ppix field in a ScrnInfoRec + points to the pixmap used by the screen's + SaveRestoreImage() function to hold the screen's + contents while switched out. + + +
+ + + Currently, aperture remapping, as described here, should not be + attempted if the driver uses the xf8_16bpp or + xf8_32bpp framebuffer layers. A pending + restructuring of VT switching will address this restriction in + the near future. + + + + Other layers may wrap the ChipEnterVT() and + ChipLeaveVT() functions if they need to take some + action when these events are received. + + + + + End of server generation + + + At the end of each server generation, the DIX layer calls + ChipCloseScreen() for each screen: + + +
+ + Bool ChipCloseScreen(int index, ScreenPtr pScreen); + +
+ 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 + ScrnInfoRec's driverPrivate field + should not be freed here because it is needed by subsequent server + generations. + + + + The ScrnInfoRec's vtSema field + should be set to FALSE once the video HW state + has been restored. + + + + Before freeing the per-screen driver data the saved + CloseScreen value should be restored to + pScreen->CloseScreen, and that function should + be called after freeing the data. + +
+
+ + + + + Optional Driver Functions + + +The functions outlined here can be called from the XFree86 common layer, +but their presence is optional. + + + + Mode Validation + + + 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: + + +
+ + ModeStatus ChipValidMode(int index, DisplayModePtr mode, + Bool verbose, int flags); + +
+ Check the passed mode for hw-specific constraints, and return the + appropriate status value. + +
+
+ + +This function may also modify the effective timings and clock of the passed +mode. These have been stored in the mode's Crtc* and +SynthClock 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 xf86PrintModes(). + + + +The function is called once for every mode in the xorg.conf Monitor section +assigned to the screen, with flags set to +MODECHECK_INITIAL. It is subsequently called for every mode +in the xorg.conf Display subsection assigned to the screen, with +flags set to MODECHECK_FINAL. In the second +case, the mode will have successfully passed all other tests. In addition, +the ScrnInfoRec's virtualX, +virtualY and displayWidth fields will have been +set as if the mode to be validated were to be the last mode accepted. + + + +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. + + + + + Free screen data + + + When a screen is deleted prior to the completion of the ScreenInit + phase the ChipFreeScreen() function is called when defined. + + +
+ + void ChipFreeScreen(int scrnindex, int flags); + +
+ Free any driver-allocated data that may have been allocated up to + and including an unsuccessful ChipScreenInit() + call. This would predominantly be data allocated by + ChipPreInit() that persists across server + generations. It would include the driverPrivate, + and any privates entries that modules may have allocated. + +
+
+ + + + + + Recommended driver functions + + +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. + + + + Save + + + Save the video state. This could be called from ChipScreenInit() and + (possibly) ChipEnterVT(). + + +
+ + void ChipSave(ScrnInfoPtr pScrn); + +
+ 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. + +
+
+ + + + Restore + + + Restore the original video state. This could be called from the + ChipLeaveVT() and ChipCloseScreen() + functions. + + +
+ + void ChipRestore(ScrnInfoPtr pScrn); + +
+ Restores the saved state from the private storage. Usually only + used for restoring text modes. + +
+
+ + + + + Initialise Mode + + + Initialise a video mode. This could be called from the + ChipScreenInit(), ChipSwitchMode() + and ChipEnterVT() functions. + + +
+ + Bool ChipModeInit(ScrnInfoPtr pScrn, DisplayModePtr mode); + +
+ Programs the hardware for the given video mode. + +
+
+ + + + + + Data and Data Structures + + + Command line data + + +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: + + + 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 + + + + +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: + + +
+ + int xf86GetVerbosity(); + +
+ Returns the value of xf86Verbose. +
+ +
+ +
+ + int xf86GetDepth(); + +
+ Returns the command line setting. If not + set on the command line, -1 is returned. +
+ +
+ +
+ + rgb xf86GetWeight(); + +
+ Returns the command line setting. If not + set on the command line, {0, 0, 0} is returned. +
+ +
+ +
+ + Gamma xf86GetGamma(); + +
+ Returns the or , + , command line settings. + If not set on the command line, {0.0, 0.0, 0.0} + is returned. +
+ +
+ +
+ + Bool xf86GetFlipPixels(); + +
+ Returns TRUE if is + present on the command line, and FALSE otherwise. +
+ +
+ +
+ + const char *xf86GetServerName(); + +
+ Returns the name of the X server from the command line. +
+ +
+ + + + Data handling + + +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 xf86InfoRec. + + + +The screen-specific data collected from the config file is stored in +screen, device, display, monitor-specific data structures that are separate +from the ScrnInfoRecs, with the appropriate elements/fields +hooked into the ScrnInfoRecs as required. The screen +config data is held in confScreenRec, device data in +the GDevRec, monitor data in the MonRec, +and display data in the DispRec. + + + +The XFree86 common layer's screen specific data (the actual data in use +for each screen) is held in the ScrnInfoRecs. As has +been outlined above, the ScrnInfoRecs are allocated at probe +time, and it is the responsibility of the Drivers' Probe() +and PreInit() 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: + +
+ command line -> config file -> probed/default data +
+ + + +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 +ScrnInfoRec, consider the balance between the convenience +of things that lots of drivers need and the size/obscurity of the +ScrnInfoRec. + + + +Per-screen driver specific data that cannot be accommodated with the +static ScrnInfoRec fields is held in a driver-defined +data structure, a pointer to which is assigned to the +ScrnInfoRec's driverPrivate field. This +is per-screen data that persists across server generations (as does the +bulk of the static ScrnInfoRec 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 ScrnInfoRec through it's privates +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 xf86.h and xf86str.h +files are visible to video drivers. Things defined in +xf86Priv.h and xf86Privstr.h are NOT +intended to be visible to video drivers, and it is an error for a driver +to include those files. + + + + + + Accessing global data + + +Some other global state information that the drivers may access via +functions is as follows: + + +
+ + Bool xf86ServerIsExiting(); + +
+ Returns TRUE if the server is at the end of a + generation and is in the process of exiting, and + FALSE otherwise. +
+ +
+ +
+ + Bool xf86ServerIsResetting(); + +
+ Returns TRUE if the server is at the end of a + generation and is in the process of resetting, and + FALSE otherwise. +
+ +
+ +
+ + Bool xf86ServerIsInitialising(); + +
+ Returns TRUE if the server is at the beginning of + a generation and is in the process of initialising, and + FALSE otherwise. +
+ +
+ +
+ + Bool xf86ServerIsOnlyProbing(); + +
+ Returns TRUE if the -probeonly command line flag + was specified, and FALSE otherwise. +
+ +
+ +
+ + Bool xf86CaughtSignal(); + +
+ Returns TRUE if the server has caught a signal, + and FALSE otherwise. +
+ +
+ + + + Allocating private data + + +A driver and any module it uses may allocate per-screen private storage +in either the ScreenRec (DIX level) or +ScrnInfoRec (XFree86 common layer level). +ScreenRec storage persists only for a single server +generation, and ScrnInfoRec storage persists across +generations for the lifetime of the server. + + + +The ScreenRec devPrivates data must be +reallocated/initialised at the start of each new generation. This is +normally done from the ChipScreenInit() function, and +Init functions for other modules that it calls. Data allocated in this +way should be freed by the driver's ChipCloseScreen() +functions, and Close functions for other modules that it calls. A new +devPrivates entry is allocated by calling the +AllocateScreenPrivateIndex() function. + + +
+ + int AllocateScreenPrivateIndex(); + +
+ This function allocates a new element in the + devPrivates field of all currently existing + ScreenRecs. The return value is the index of this + new element in the devPrivates array. The + devPrivates field is of type + DevUnion: + + + typedef union _DevUnion { + pointer ptr; + long val; + unsigned long uval; + pointer (*fptr)(void); + } DevUnion; + + + 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 -1 when there is an + error allocating the new index. + + +
+
+ + +The ScrnInfoRec privates data persists +for the life of the server, so only needs to be allocated once. This +should be done from the ChipPreInit() function, and Init +functions for other modules that it calls. Data allocated in this way +should be freed by the driver's ChipFreeScreen() functions, +and Free functions for other modules that it calls. A new +privates entry is allocated by calling the +xf86AllocateScrnInfoPrivateIndex() function. + + +
+ + int xf86AllocateScrnInfoPrivateIndex(); + +
+ This function allocates a new element in the privates + field of all currently existing ScrnInfoRecs. + The return value is the index of this new element in the + privates array. The privates + field is of type DevUnion: + + + typedef union _DevUnion { + pointer ptr; + long val; + unsigned long uval; + pointer (*fptr)(void); + } DevUnion; + + + 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 ScreenRec + (AllocateScreenPrivateIndex()) differs in this + respect by returning -1 when the allocation fails. + + +
+
+ + + + + Keeping Track of Bus Resources + + + Theory of Operation + + +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 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: + + + + 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). + + + + A resource marked disabled during OPERATING state will be ignored + entirely. + + + + 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. + + + + 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: + + + + 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. + + + + 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. + + + + 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. + + + + + Resource Types + + +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 + + + + its physical properties i.e., 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 necessary 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/xf86Resources.h. + + + + + Available Functions + + +The functions provided for resource management are listed in their order +of use in the driver. + + + + Probe Phase + + +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: + + +
+ + int xf86MatchPciInstances(const char *driverName, int vendorID, + SymTabPtr chipsets, PciChipsets *PCIchipsets, + GDevPtr *devList, int numDevs, DriverPtr drvp, + int **foundEntities); + +
+ This function finds matches between PCI cards that a driver supports + and config file device sections. It is intended for use in the + ChipProbe() function of drivers for PCI cards. + Only probed PCI devices with a vendor ID matching + vendorID are considered. devList + and numDevs are typically those found from + calling xf86MatchDevice(), and represent the active + config file device sections relevant to the driver. + PCIchipsets 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 BusID entry it + can only match the primary video device. Secondary devices are + only matched with device sections that have a matching + BusID 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 + chipsets and PCIchipsets lists. + The PCIchipsets list includes a list of the PCI + device IDs supported by the driver. The list should be terminated + with an entry with PCI ID -1". The + chipsets list is a table mapping the driver's + internal chipset tokens to names, and should be terminated with + a NULL entry. Only those entries with a + corresponding entry in the PCIchipsets 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 vendorID to + 0, and OR each devID in the list with (the + vendor ID << 16). + + + + Entity index numbers for confirmed matches are returned as an + array via foundEntities. The PCI information, + chipset token and device section for each match are found in the + EntityInfoRec referenced by the indices. + + + + The function return value is the number of confirmed matches. A + return value of -1 indicates an internal error. + The returned foundEntities array should be freed + by the driver with xfree() when it is no longer + needed in cases where the return value is greater than zero. + + +
+ +
+ + int xf86MatchIsaInstances(const char *driverName, + SymTabPtr chipsets, IsaChipsets *ISAchipsets, + DriverPtr drvp, FindIsaDevProc FindIsaDevice, + GDevPtr *devList, int numDevs, + int **foundEntities); + +
+ This function finds matches between ISA cards that a driver supports + and config file device sections. It is intended for use in the + ChipProbe() function of drivers for ISA cards. + devList and numDevs are + typically those found from calling xf86MatchDevice(), + and represent the active config file device sections relevant to + the driver. ISAchipsets is a table that provides + a mapping between the driver's internal chipset tokens and the + resource classes. FindIsaDevice is a + driver-provided function that probes the hardware and returns the + chipset token corresponding to what was detected, and + -1 if nothing was detected. + + + + If the config file device section contains a chipset entry, then + it is checked against the chipsets list. When + no chipset entry is present, the FindIsaDevice + function is called instead. + + + + Entity index numbers for confirmed matches are returned as an + array via foundEntities. The chipset token and + device section for each match are found in the + EntityInfoRec referenced by the indices. + + + + The function return value is the number of confirmed matches. A + return value of -1 indicates an internal error. + The returned foundEntities array should be freed + by the driver with xfree() when it is no longer + needed in cases where the return value is greater than zero. + + +
+ + +These two helper functions make use of several core functions that are +available at the driver level: + + +
+ + Bool xf86ParsePciBusString(const char *busID, int *bus, + int *device, int *func); + +
+ Takes a BusID string, and if it is in the correct + format, returns the PCI bus, device, + func 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 FALSE. + + +
+ +
+ + Bool xf86ComparePciBusString(const char *busID, int bus, + int device, int func); + +
+ Compares a BusID string with PCI bus, + device, func values. If they + match TRUE is returned, and FALSE + if they don't. + + +
+ +
+ + Bool xf86ParseIsaBusString(const char *busID); + +
+ Compares a BusID string with the ISA bus ID string + ("ISA" or "ISA:"). If they match TRUE is returned, + and FALSE if they don't. + + +
+ +
+ + Bool xf86CheckPciSlot(int bus, int device, int func); + +
+ Checks if the PCI slot bus:device:func has been + claimed. If so, it returns FALSE, and otherwise + TRUE. + + +
+ +
+ + int xf86ClaimPciSlot(int bus, int device, int func, DriverPtr drvp, + int chipset, GDevPtr dev, Bool active); + +
+ 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 + -1 if the claim fails. This function should always + succeed if xf86CheckPciSlot() returned + TRUE for the same PCI slot. + + +
+ +
+ + Bool xf86IsPrimaryPci(void); + +
+ This function returns TRUE if the primary card is + a PCI device, and FALSE otherwise. + + +
+ +
+ + int xf86ClaimIsaSlot(DriverPtr drvp, int chipset, + GDevPtr dev, Bool active); + +
+ This allocates an entity record entity and initialise the data + structures. The return value is the index of the newly allocated + entity record. + + +
+ +
+ + Bool xf86IsPrimaryIsa(void); + +
+ This function returns TRUE if the primary card is + an ISA (non-PCI) device, and FALSE otherwise. + + +
+ + +Two helper functions are provided to aid configuring entities: + + +
+ + ScrnInfoPtr xf86ConfigPciEntity(ScrnInfoPtr pScrn, + int scrnFlag, int entityIndex, + PciChipsets *p_chip, + resList res, EntityProc init, + EntityProc enter, EntityProc leave, + pointer private); + + ScrnInfoPtr xf86ConfigIsaEntity(ScrnInfoPtr pScrn, + int scrnFlag, int entityIndex, + IsaChipsets *i_chip, + resList res, EntityProc init, + EntityProc enter, EntityProc leave, + pointer private); + +
+ These functions are used to register the non-relocatable resources + for an entity, and the optional entity-specific Init, Enter and + Leave 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 ScrnInfoRec is allocated + if the pScrn argument is NULL. +The + return value is TRUE when successful. The init, enter, leave + functions are defined as follows: + +
+ + typedef void (*EntityProc)(int entityIndex, + pointer private); + +
+ + They are passed the entity index and a pointer to a private scratch + area. This can be set up during Probe() and + its address can be passed to + xf86ConfigIsaEntity() and + xf86ConfigPciEntity() as the last argument. + + +
+ + +These two helper functions make use of several core functions that are +available at the driver level: + +
+ + void xf86ClaimFixedResources(resList list, int entityIndex); + +
+ 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 + Probe() phase. + + +
+ +
+ + Bool xf86SetEntityFuncs(int entityIndex, EntityProc init, + EntityProc enter, EntityProc leave, pointer); + +
+ This function registers with an entity the init, + enter, leave functions along + with the pointer to their private area. + + +
+ +
+ + void xf86AddEntityToScreen(ScrnInfoPtr pScrn, int entityIndex); + +
+ This function associates the entity referenced by + entityIndex with the screen. + + +
+ + + + + PreInit Phase + + +During this phase the remaining resources should be registered. +PreInit() should call xf86GetEntityInfo() +to obtain a pointer to an EntityInfoRec for each entity +it is able to drive and check if any resource are listed in its +resources field. If resources registered in the Probe +phase have been rejected in the post-Probe phase +(resources is non-NULL), then the driver should +decide if it can continue without using these or if it should fail. + + +
+ + EntityInfoPtr xf86GetEntityInfo(int entityIndex); + +
+ This function returns a pointer to the EntityInfoRec + referenced by entityIndex. The returned + EntityInfoRec should be freed with + xfree() when no longer needed. + + +
+ + +Several functions are provided to simplify resource registration: +
+ + Bool xf86IsEntityPrimary(int entityIndex); + +
+ This function returns TRUE if the entity referenced + by entityIndex is the primary display device (i.e., + the one initialised at boot time and used in text mode). + + +
+ +
+ + Bool xf86IsScreenPrimary(int scrnIndex); + +
+ This function returns TRUE if the primary entity + is registered with the screen referenced by + scrnIndex. + + +
+ +
+ + pciVideoPtr xf86GetPciInfoForEntity(int entityIndex); + +
+ This function returns a pointer to the pciVideoRec + for 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); + +
+ This function 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 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 xf86ReallocatePciResources(). + When the registration succeeds, the return value is + NULL. + + +
+ + +
+ + resPtr xf86ReallocatePciResources(int entityIndex, resPtr pRes); + +
+ This function takes a list of PCI resources that need to be + reallocated and returns NULL when all relocations are + successful. + xf86RegisterResources() 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. + + +
+ + +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); + +
+ This function 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 align_mask. + Optionally a list of resource ranges which should be avoided within + the window can be supplied. On failure a zero-length range of + type ResEnd will be returned. + +
+ +
+ + resRange xf86GetSparse(long type, memType fixed_bits, + memType decode_mask, memType address_mask, + resPtr avoid); + +
+ 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 address_mask which marks all + bits of the mask part of the address, the decode_mask + 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 + ResEnd. Optionally it might be passed a list of + resource ranges to avoid. + + +
+ + + +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 xf86FixPciResource() can be used to do this: +
+ + Bool xf86FixPciResource(int entityIndex, unsigned int prt, + CARD32 alignment, long type); + +
+ This function fixes a PCI resource allocation. The + prt parameter contains the number of the PCI base + register that needs to be fixed (0-5, and + 6 for the BIOS base register). The size is + specified by the alignment. Since PCI resources need to span an + integral range of size 2ˆn, the alignm ent 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(). The return value is + TRUE when the function succeeds. + + +
+ +
+ + Bool xf86CheckPciMemBase(pciVideoPtr pPci, memType base); + +
+ 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. + + +
+ + + +The driver may replace the generic access control functions for an entity. +This is done with the xf86SetAccessFuncs(): +
+ + void xf86SetAccessFuncs(EntityInfoPtr pEnt, + xf86SetAccessFuncPtr funcs, + xf86SetAccessFuncPtr oldFuncs); + + with: + + typedef struct { + xf86AccessPtr mem; + xf86AccessPtr io; + xf86AccessPtr io_mem; + } xf86SetAccessFuncRec, *xf86SetAccessFuncPtr; + +
+ 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 record. + 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 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. + + +
+ + + +To find out if a specific resource range conflicts with another +resource the xf86ChkConflict() function may be used: +
+ + memType xf86ChkConflict(resRange *rgp, int entityIndex); + +
+ This function checks if the resource range rgp 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. + + +
+ + + +The OPERATING state properties of previously registered fixed resources +can be set with the xf86SetOperatingState() function: +
+ + resPtr xf86SetOperatingState(resList list, int entityIndex, + int mask); + +
+ This function is used to set the status 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 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 + 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). + + +
+ + + +The following two functions are provided for special cases: +
+ + void xf86RemoveEntityFromScreen(ScrnInfoPtr pScrn, int entityIndex); + +
+ 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. + + +
+ +
+ + void xf86DeallocateResourcesForEntity(int entityIndex, long type); + +
+ This function deallocates all resources of a given type registered + for a certain entity from the resource broker list. + + +
+ + + + + + ScreenInit Phase + + +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 racIoFlags and racMemFlags fields of the +ScrnInfoRec 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 rac/xf86RAC.h. They 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 ChipAdjustFrame() + + + + +The flags are ORed together. + + + + + + + Config file <quote>Option</quote> entries + + +Option entries are permitted in most sections and subsections of the +config file. There are two forms of option entries: + + + Option "option-name" + + A boolean option. + + Option "option-name" "option-value" + + An option with an arbitrary value. + + + + + +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. + + +
+ + pointer xf86FindOption(pointer options, const char *name); + +
+ 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 + NULL if no match is found. + + +
+ +
+ + char *xf86FindOptionValue(pointer options, const char *name); + +
+ 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 + ("") is returned. Returns NULL + if no match is found. + + +
+ +
+ + void xf86MarkOptionUsed(pointer option); + +
+ Takes a handle for an option, and marks that option as used. + + +
+ +
+ + void xf86MarkOptionUsedByName(pointer options, const char *name); + +
+ Takes a list of options and an option name and marks the first + option entry in the list matching the name as used. + + +
+ + +Next, the higher level functions that most drivers would use. + +
+ + void xf86CollectOptions(ScrnInfoPtr pScrn, pointer extraOpts); + +
+ Collect the options from each of the config file sections used by + the screen (pScrn) and return the merged list as + pScrn->options. This function requires that + pScrn->confScreen, pScrn->display, + pScrn->monitor, + pScrn->numEntities, and + pScrn->entityList are initialised. + extraOpts may optionally be set to an additional + list of options to be combined with the others. The order of + precedence for options is extraOpts, display, + confScreen, monitor, device. + + +
+ +
+ + void xf86ProcessOptions(int scrnIndex, pointer options, + OptionInfoPtr optinfo); + +
+ Processes a list of options according to the information in the + array of OptionInfoRecs (optinfo). + The resulting information is stored in the value + fields of the appropriate optinfo entries. The + found fields are set to TRUE + when an option with a value of the correct type if found, and + FALSE otherwise. The type 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 ChipProbe() function) a + scrnIndex value of -1 should be + used. + + + + NOTE 2: Given that this function stores into the + OptionInfoRecs pointed to by optinfo, + the caller should ensure the OptionInfoRecs are + (re-)initialised before the call, especially if the caller expects + to use the predefined option values as defaults. + + + + The OptionInfoRec is defined as follows: + + + 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_PERCENT, + 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; + + + + OPTV_FREQ 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 freq.units, and the scaled frequency + is stored in freq.freq. When no unit is specified, + freq.units is set to 0, and + freq.freq is unscaled. + + + + OPTV_PERCENT can be used for option values that are + specified in percent (e.g. "20%"). These values are a floating point + number with a percent sign appended. If the percent sign is missing, + the parser will fail to match the value. + + + + Typical usage is to setup an array of + OptionInfoRecs with all fields initialised. + The value and found fields get + set by xf86ProcessOptions(). For cases where the + value parsing is more complex, the driver should specify + OPTV_STRING, and parse the string itself. An + example of using this option handling is included in the + Sample Driver section. + + +
+ +
+ + void xf86ShowUnusedOptions(int scrnIndex, pointer options); + +
+ 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 ChipScreenInit() function, but only + when serverGeneration == 1 + +
+ +
+ + OptionInfoPtr xf86TokenToOptinfo(const OptionInfoRec *table, + int token); + +
+ Returns a pointer to the OptionInfoRec in + table with a token field matching + token. Returns NULL if no match + is found. + + +
+ +
+ + Bool xf86IsOptionSet(const OptionInfoRec *table, int token); + +
+ Returns the found field of the + OptionInfoRec in table with a + token field matching token. This + can be used for options of all types. Note that for options of + type OPTV_BOOLEAN, it isn't sufficient to check + this to determine the value of the option. Returns + FALSE if no match is found. + + +
+ +
+ + char *xf86GetOptValString(const OptionInfoRec *table, int token); + +
+ Returns the value.str field of the + OptionInfoRec in table with a + token field matching token. Returns + NULL if no match is found. + + +
+ +
+ + Bool xf86GetOptValInteger(const OptionInfoRec *table, int token, + + int *value); + +
+ Returns via *value the value.num + field of the OptionInfoRec in table + with a token field matching token. + *value 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 + xf86IsOptionSet(). + + +
+ +
+ + Bool xf86GetOptValULong(const OptionInfoRec *table, int token, + unsigned long *value); + +
+ Like xf86GetOptValInteger(), except the value is + treated as an unsigned long. + + +
+ +
+ + Bool xf86GetOptValReal(const OptionInfoRec *table, int token, + double *value); + +
+ Like xf86GetOptValInteger(), except that + value.realnum is used. + + +
+ +
+ + Bool xf86GetOptValFreq(const OptionInfoRec *table, int token, + OptFreqUnits expectedUnits, double *value); + +
+ Like xf86GetOptValInteger(), except that the + value.freq data is returned. The frequency value + is scaled to the units indicated by expectedUnits. + The scaling is exact when the units were specified explicitly in + the option's value. Otherwise, the expectedUnits + field is used as a hint when doing the scaling. In this case, + values larger than 1000 are assumed to have be + specified in the next smallest units. For example, if the Option + value is "10000" and expectedUnits is OPTUNITS_MHZ, + the value returned is 10. + + +
+ +
+ + Bool xf86GetOptValBool(const OptionInfoRec *table, int token, Bool *value); + +
+ This function is used to check boolean options + (OPTV_BOOLEAN). If the function return value is + FALSE, it means the option wasn't set. Otherwise + *value is set to the boolean value indicated by + the option's value. No option value is interpreted + as TRUE. Option values meaning TRUE + are "1", "yes", "on", "true", and option values meaning + FALSE 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. + *value is not changed when the option isn't present. + It should normally be set to a default value before calling this + function. + + +
+ +
+ + Bool xf86ReturnOptValBool(const OptionInfoRec *table, int token, Bool def); + +
+ This function is used to check boolean options + (OPTV_BOOLEAN). If the option is set, its value + is returned. If the options is not set, the default value specified + by def is returned. The option interpretation is + the same as for xf86GetOptValBool(). + + +
+ +
+ + int xf86NameCmp(const char *s1, const char *s2); + +
+ This function should be used when comparing strings from the config + file with expected values. It works like strcmp(), + but is not case sensitive and space, tab, and _ 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. + + +
+ + + + Modules, Drivers, Include Files and Interface Issues + + +NOTE: this section is incomplete. + + + + + Include files + + +The following include files are typically required by video drivers: + +
+ All drivers should include these: + + "xf86.h" + "xf86_OSproc.h" + "xf86_ansic.h" + "xf86Resources.h" + + Wherever inb/outb (and related things) are used the following should be + included: + + "compiler.h" + + Note: in drivers, this must be included after "xf86_ansic.h". + + + + Drivers that need to access PCI vendor/device definitions need this: + + "xf86PciInfo.h" + + + + + Drivers that need to access the PCI config space need this: + + "xf86Pci.h" + + + + + Drivers that initialise a SW cursor need this: + + "mipointer.h" + + + + + All drivers implementing backing store need this: + + "mibstore.h" + + + + + All drivers using the mi colourmap code need this: + + "micmap.h" + + + + + If a driver uses the vgahw module, it needs this: + + "vgaHW.h" + + + + + Drivers supporting VGA or Hercules monochrome screens need: + + "xf1bpp.h" + + + + + Drivers supporting VGA or EGC 16-colour screens need: + + "xf4bpp.h" + + + + + Drivers using cfb need: + + #define PSZ 8 + #include "cfb.h" + #undef PSZ + + + + + Drivers supporting bpp 16, 24 or 32 with cfb need one or more of: + + "cfb16.h" + "cfb24.h" + "cfb32.h" + + + + + If a driver uses XAA, it needs these: + + "xaa.h" + "xaalocal.h" + + + + + If a driver uses the fb manager, it needs this: + + "xf86fbman.h" + + +
+ + + +Non-driver modules should include "xf86_ansic.h" to get the correct +wrapping of ANSI C/libc functions. + + + +All modules must NOT include any system include files, or the following: + + + "xf86Priv.h" + "xf86Privstr.h" + "xf86_OSlib.h" + "Xos.h" + + + + +In addition, "xf86_libc.h" must not be included explicitly. It is +included implicitly by "xf86_ansic.h". + + + + + + + Offscreen Memory Manager + + +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 +xf86fbman.h): + + + 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 + ) + + + + +The function: + + Bool xf86FBManagerRunning(ScreenPtr pScreen); + + +can be used by an extension to check if the driver has initialized +the memory manager. The manager is not available if this returns +FALSE and the functions above will all fail. + + + + +xf86AllocateOffscreenArea() can be used to request a +rectangle of dimensions width × height +(in pixels) from unused offscreen memory. granularity +specifies that the leftmost edge of the rectangle must lie on some +multiple of granularity pixels. A granularity of zero +means the same thing as a granularity of one - no alignment preference. +A MoveAreaCallback can be provided to notify the requester +when the offscreen area is moved. If no MoveAreaCallback +is supplied then the area is considered to be immovable. The +privData field will be stored in the manager's internal +structure for that allocated area and will be returned to the requester +in the FBArea passed via the +MoveAreaCallback. An optional +RemoveAreaCallback 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 RemoveAreaCallback) 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. + + + +xf86AllocateOffscreenArea() returns NULL +if it was unable to allocate the requested area. When no longer needed, +areas should be freed with xf86FreeOffscreenArea(). + + + +xf86ResizeOffscreenArea() resizes an existing +FBArea. xf86ResizeOffscreenArea() +returns TRUE if the resize was successful. If +xf86ResizeOffscreenArea() returns FALSE, +the original FBArea is left unmodified. Resizing an +area maintains the area's original granularity, +devPrivate, and MoveAreaCallback. +xf86ResizeOffscreenArea() has considerably less overhead +than freeing the old area then reallocating the new size, so it should +be used whenever possible. + + + +The function: + + Bool xf86QueryLargestOffscreenArea( + ScreenPtr pScreen, + int *width, int *height, + int granularity, + int preferences, + int priority + ); + + +is provided to query the width and height of the largest single +FBArea allocatable given a particular priority. +preferences can be one of the following to indicate +whether width, height or area should be considered when determining +which is the largest single FBArea available. + + + FAVOR_AREA_THEN_WIDTH + FAVOR_AREA_THEN_HEIGHT + FAVOR_WIDTH_THEN_AREA + FAVOR_HEIGHT_THEN_AREA + + + + +priority is one of the following: + +
+ + PRIORITY_LOW +
+ Return the largest block available without stealing anyone else's + space. This corresponds to the priority of allocating a + FBArea when a RemoveAreaCallback + is provided. +
+ + + + PRIORITY_NORMAL +
+ 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 FBArea without providing a + RemoveAreaCallback. +
+ + + + PRIORITY_EXTREME +
+ Return the largest block available if all FBAreas + that aren't locked down were expunged from memory first. This + corresponds to any allocation made directly after a call to + xf86PurgeUnlockedOffscreenAreas(). +
+ + +
+ + + + +The function: + + + Bool xf86PurgeUnlockedOffscreenAreas(ScreenPtr pScreen); + + +is provided as an extreme method to free up offscreen memory. This +will remove all removable FBArea allocations. + + + + +Initialization of the XFree86 framebuffer manager is done via + + + Bool xf86InitFBManager(ScreenPtr pScreen, BoxPtr FullBox); + + +FullBox represents the area of the framebuffer that the +manager is allowed to manage. This is typically a box with a width of +pScrn->displayWidth 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. + + + +xf86InitFBManager() 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. + + + Bool xf86InitFBManagerRegion(ScreenPtr pScreen, + RegionPtr FullRegion); + + +xf86InitFBManagerRegion(), unlike +xf86InitFBManager(), does not remove the area used for +the visible screen so that area should not be included in the region +passed to the function. xf86InitFBManagerRegion() 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). + + + + + + Colormap Handling + + +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 +xf86HandleColormaps() function. + +
+ + Bool xf86HandleColormaps(ScreenPtr pScreen, int maxColors, + int sigRGBbits, LoadPaletteFuncPtr loadPalette, + SetOverscanFuncPtr setOverscan, + unsigned int flags); + +
+ This function must be called after the default colormap has been + initialised. The pScrn->gamma field must also + be initialised, preferably by calling xf86SetGamma(). + maxColors is the number of entries in the palette. + sigRGBbits is the size in bits of each color + component in the DAC's palette. loadPalette + is a driver-provided function for loading a colormap into the + hardware, and is described below. setOverscan 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 + setOverscan function programs the overscan index. + It shouldn't normally be used for depths other than 8. + setOverscan should be set to NULL + when it isn't needed. flags may be set to the + following (which may be ORed together): + + + + CMAP_PALETTED_TRUECOLOR + + the TrueColor visual is paletted and is + just a special case of DirectColor. + This flag is only valid for + bpp > 8. + + + + CMAP_RELOAD_ON_MODE_SWITCH + + 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. + + + + CMAP_LOAD_EVEN_IF_OFFSCREEN + + reload the colormap even if the screen + is switched out of the server's VC. + The palette is not 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. + + + + + + + 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. + + +
+ +
+ + void LoadPalette(ScrnInfoPtr pScrn, int numColors, int *indices, + LOCO *colors, VisualPtr pVisual); + +
+ LoadPalette() is a driver-provided function for + loading a colormap into hardware. colors is the + array of RGB values that represent the full colormap. + indices is a list of index values into the colors + array. These indices indicate the entries that need to be updated. + numColors is the number of the indices to be + updated. + + +
+ +
+ + void SetOverscan(ScrnInfoPtr pScrn, int overscan); + +
+ SetOverscan() is a driver-provided function for + programming the overscan 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. + + +
+
+ + + + + DPMS Extension + + +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). + + +
+ + Bool xf86DPMSInit(ScreenPtr pScreen, DPMSSetProcPtr set, int flags); + +
+ This function registers a driver's DPMS level programming function + set. It also checks + pScrn->options for the "dpms" option, and when + present marks DPMS as being enabled for that screen. The + set function is called whenever the DPMS level + changes, and is used to program the requested level. + flags is currently not used, and should be + 0. If the initialisation fails for any reason, + including when there is no DPMS support in the core server, the + function returns FALSE. + + +
+ + + +Drivers that implement DPMS support must provide the following function, +that gets called when the DPMS level is changed: + + +
+ + void ChipDPMSSet(ScrnInfoPtr pScrn, int level, int flags); + +
+ Program the DPMS level specified by level. Valid + values of level are DPMSModeOn, + DPMSModeStandby, DPMSModeSuspend, + DPMSModeOff. These values are defined in + "extensions/dpms.h". + + +
+ + + + + + DGA Extension + + +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. + + +
+ + Bool DGAInit(ScreenPtr pScreen, DGAFunctionPtr funcs, + DGAModePtr modes, int num); + +/** 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; + + + + + num + + Can be ignored. The DGA DDX will assign these numbers. + + + + mode + + A pointer to the DisplayModeRec for this mode. + + + + flags + + The following flags are defined and may be OR'd together: + + + + DGA_CONCURRENT_ACCESS + + Indicates that the driver supports concurrent graphics + accelerator and linear framebuffer access. + + + + + DGA_FILL_RECT + DGA_BLIT_RECT + DGA_BLIT_RECT_TRANS + + Indicates that the driver supports the FillRect, BlitRect + or BlitTransRect functions in this mode. + + + + + DGA_PIXMAP_AVAILABLE + + 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. + + + + + DGA_INTERLACED + DGA_DOUBLESCAN + + Indicates that these are interlaced or double scan modes. + + + + + + + imageWidth + imageHeight + + These are the dimensions of the linear framebuffer + accessible by the client. + + + + + pixmapWidth + pixmapHeight + + These are the dimensions of the area of the + framebuffer accessible by the graphics accelerator. + + + + + bytesPerScanline + + Pitch of the framebuffer in bytes. + + + + + byteOrder + + Usually the same as + pScrn->imageByteOrder. + + + + + depth + + The depth of the framebuffer in this mode. + + + + + bitsPerPixel + + The number of bits per pixel in this mode. + + + + + red_mask + green_mask + blue_mask + + The RGB masks for this mode, if applicable. + + + + + viewportWidth + viewportHeight + + Dimensions of the visible part of the framebuffer. + Usually mode->HDisplay and + mode->VDisplay. + + + + + xViewportStep + yViewportStep + + The granularity of x and y viewport positions that + the driver supports in this mode. + + + + + maxViewportX + maxViewportY + + The maximum viewport position supported by the + driver in this mode. + + + + viewportFlags + + The following may be OR'd together: + + + + DGA_FLIP_IMMEDIATE + + The driver supports immediate viewport changes. + + + + DGA_FLIP_RETRACE + + + The driver supports viewport changes at retrace. + + + + + + offset + + The offset into the linear framebuffer that corresponds to + pixel (0,0) for this mode. + + + + address + + The virtual address of the framebuffer as mapped by the driver. + This is needed when DGA_PIXMAP_AVAILABLE is set. + + + + + +/** 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; + + + +
+ + Bool OpenFramebuffer (pScrn, name, mem, size, offset, extra); + +
+ OpenFramebuffer() 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. + + + + name + + The name of the device to open or NULL if + there is no special device to open. A NULL + name tells the client that it should open whatever device + one would usually open to access physical memory. + + + + mem + + The physical address of the start of the framebuffer. + + + + size + + The size of the framebuffer in bytes. + + + + offset + + Any offset into the device, if applicable. + + + + flags + + Any additional information that the client may need. + Currently, only the DGA_NEED_ROOT flag is + defined. + + + +
+
+ +
+ + void CloseFramebuffer (pScrn); + +
+ CloseFramebuffer() merely informs the driver (if it + even cares) that client no longer needs to access the framebuffer + directly. This function is optional. + + +
+ +
+ + Bool SetMode (pScrn, pMode); + +
+ SetMode() tells the driver to initialize the mode + passed to it. If pMode is NULL, + then the driver should restore the original pre-DGA mode. + + +
+ +
+ + void SetViewport (pScrn, x, y, flags); + +
+ SetViewport() tells the driver to make the upper + left-hand corner of the visible screen correspond to coordinate + (x,y) on the framebuffer. flags + currently defined are: + + + + DGA_FLIP_IMMEDIATE + + The viewport change should occur immediately. + + + + DGA_FLIP_RETRACE + + The viewport change should occur at the + vertical retrace, but this function should + return sooner if possible. + + + + + + The (x,y) 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 + xViewportStep and yViewportStep + for the current mode. + +
+ +
+ + int GetViewport (pScrn); + +
+ GetViewport() 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. + + +
+ +
+ + void Sync (pScrn); + +
+ This function should ensure that any graphics accelerator operations + have finished. This function should not return until the graphics + accelerator is idle. + + +
+ +
+ + void FillRect (pScrn, x, y, w, h, color); + +
+ This optional function should fill a rectangle + w × h located at + (x,y) in the given color. + + +
+ +
+ + void BlitRect (pScrn, srcx, srcy, w, h, dstx, dsty); + +
+ This optional function should copy an area + w × h located at + (srcx,srcy) to location (dstx,dsty). + This function will need to handle copy directions as appropriate. + + +
+ +
+ + void BlitTransRect (pScrn, srcx, srcy, w, h, dstx, dsty, color); + +
+ This optional function is the same as BlitRect except that pixels + in the source corresponding to the color key color + should be skipped. + + +
+
+ + + + + The XFree86 X Video Extension (Xv) Device Dependent Layer + + +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 XF86VideoAdaptorRecs +as described later in this document and passing a list of +XF86VideoAdaptorPtr pointers to the following function: + + + Bool xf86XVScreenInit(ScreenPtr pScreen, + XF86VideoAdaptorPtr *adaptPtrs, + int num); + + + + +After doing this, the extension will report video adaptors as being +available, providing the data in their respective +XF86VideoAdaptorRecs was valid. +xf86XVScreenInit() copies 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 XF86VideoAdaptorRec: + + +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; + + + +Each adaptor will have its own XF86VideoAdaptorRec. The fields are +as follows: + + + + type + + This can be any of the following flags OR'd together. + + + + XvInputMask + XvOutputMask + + These refer to the target drawable and are similar to a Window's + class. XvInputMask indicates that the adaptor + can put video into a drawable. XvOutputMask + indicates that the adaptor can get video from a drawable. + + + + XvVideoMask + XvStillMask + XvImageMask + + These indicate that the adaptor supports video, still or + image primitives respectively. + + + + XvWindowMask + XvPixmapMask + + These indicate the types of drawables the adaptor is capable + of rendering into. At the moment, Pixmap rendering is not + supported and the XvPixmapMask flag is ignored. + + + + + + + flags + + Currently, the following flags are defined: + + + + VIDEO_NO_CLIPPING + + 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 + drw_x, drw_y, + drw_w and drw_h 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. + + + + + + VIDEO_INVERT_CLIPLIST + + 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. + + + + + + VIDEO_OVERLAID_STILLS + + 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. + + + + + + VIDEO_OVERLAID_IMAGES + + Same as VIDEO_OVERLAID_STILLS but for images. + + + + + VIDEO_CLIP_TO_VIEWPORT + + 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. + + + + + + + name + + The name of the adaptor. + + + + + nEncodings + pEncodings + + The number of encodings the adaptor is capable of and pointer + to the XF86VideoEncodingRec array. The + XF86VideoEncodingRec 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. + + + + + nFormats + pFormats + + The number of formats the adaptor is capable of and pointer to + the XF86VideoFormatRec array. The + XF86VideoFormatRec is described later on. + + + + + nPorts + pPortPrivates + + 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. pPortPrivates 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. + + + + + nAttributes + pAttributes + + The number of attributes recognized by the adaptor and a pointer to + the array of XF86AttributeRecs. The + XF86AttributeRec is described later on. + + + + + nImages + pImages + + The number of XF86ImageRecs supported by the adaptor + and a pointer to the array of XF86ImageRecs. The + XF86ImageRec is described later on. + + + + + + PutVideo PutStill GetVideo GetStill StopVideo + SetPortAttribute GetPortAttribute QueryBestSize PutImage + QueryImageAttributes + + + These functions define the DDX->driver interface. In each + case, the pointer data 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: + + + + PutVideo, PutStill and + the image routines PutImage and + QueryImageAttributes are not required when the + adaptor type does not contain XvInputMask. + + + + GetVideo and GetStill + are not required when the adaptor type does not contain + XvOutputMask. + + + + GetVideo and PutVideo + are not required when the adaptor type does not contain + XvVideoMask. + + + + GetStill and PutStill + are not required when the adaptor type does not contain + XvStillMask. + + + + PutImage and QueryImageAttributes + are not required when the adaptor type does not contain + XvImageMask. + + + + + + + + With the exception of QueryImageAttributes, these + functions should return Success if the operation was + completed successfully. They can return XvBadAlloc + otherwise. QueryImageAttributes returns the size + of the XvImage queried. + + + + If the VIDEO_NO_CLIPPING + flag is set, the clipBoxes may be ignored by + the driver. ClipBoxes is an X-Y + banded region identical to those used throughout the server. + The clipBoxes represent the visible portions of the area determined + by drw_x, drw_y, + drw_w and drw_h 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 VIDEO_INVERT_CLIPLIST, + clipBoxes will indicate the areas of the primitive + which are obscured rather than the areas visible. + + + + +
+ + typedef int (* PutVideoFuncPtr)( ScrnInfoPtr pScrn, + short vid_x, short vid_y, short drw_x, short drw_y, + short vid_w, short vid_h, short drw_w, short drw_h, + RegionPtr clipBoxes, pointer data ); + +
+ This indicates that the driver should take a subsection + vid_w by vid_h at location + (vid_x,vid_y) from the video stream and direct + it into the rectangle drw_w by drw_h + at location (drw_x,drw_y) 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. + + +
+ +
+ + typedef int (* PutStillFuncPtr)( ScrnInfoPtr pScrn, + short vid_x, short vid_y, short drw_x, short drw_y, + short vid_w, short vid_h, short drw_w, short drw_h, + RegionPtr clipBoxes, pointer data ); + +
+ This is same as PutVideo except that the driver + should place only one frame from the stream on the screen. + + +
+ +
+ + typedef int (* GetVideoFuncPtr)( ScrnInfoPtr pScrn, + short vid_x, short vid_y, short drw_x, short drw_y, + short vid_w, short vid_h, short drw_w, short drw_h, + RegionPtr clipBoxes, pointer data ); + +
+ This is same as PutVideo 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. + + +
+ +
+ + typedef int (* GetStillFuncPtr)( ScrnInfoPtr pScrn, + short vid_x, short vid_y, short drw_x, short drw_y, + short vid_w, short vid_h, short drw_w, short drw_h, + RegionPtr clipBoxes, pointer data ); + +
+ This is the same as GetVideo except that the + driver should place only one frame from the screen into the + output stream. + + +
+ +
+ + typedef void (* StopVideoFuncPtr)(ScrnInfoPtr pScrn, + pointer data, Bool cleanup); + +
+ This indicates the driver should stop displaying the video. + This is used to stop both input and output video. The + cleanup 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 + cleanup 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. + + +
+
+ + typedef int (* SetPortAttributeFuncPtr)(ScrnInfoPtr pScrn, + Atom attribute,INT32 value, pointer data); + + + + typedef int (* GetPortAttributeFuncPtr)(ScrnInfoPtr pScrn, + Atom attribute,INT32 *value, pointer data); + +
+ 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: + + XV_ENCODING + XV_HUE + XV_SATURATION + XV_BRIGHTNESS + XV_CONTRAST + + but the driver may recognize as many atoms as it wishes. If + a requested attribute is unknown by the driver it should return + BadMatch. XV_ENCODING is the + attribute intended to let the client specify which video + encoding the particular port should be using (see the description + of XF86VideoEncodingRec below). If the + requested encoding is unsupported, the driver should return + XvBadEncoding. If the value lies outside the + advertised range BadValue may be returned. + Success should be returned otherwise. + + +
+ +
+ + typedef void (* QueryBestSizeFuncPtr)(ScrnInfoPtr pScrn, + Bool motion, short vid_w, short vid_h, + short drw_w, short drw_h, + unsigned int *p_w, unsigned int *p_h, pointer data); + +
+ QueryBestSize provides the client with a way + to query what the destination dimensions would end up being + if they were to request that an area + vid_w by vid_h from the video + stream be scaled to rectangle of + drw_w by drw_h 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. + + +
+ +
+ + typedef int (* PutImageFuncPtr)( ScrnInfoPtr pScrn, + short src_x, short src_y, short drw_x, short drw_y, + short src_w, short src_h, short drw_w, short drw_h, + int image, char *buf, short width, short height, + Bool sync, RegionPtr clipBoxes, pointer data ); + +
+ This is similar to PutStill except that the + source of the video is not a port but the data stored in a system + memory buffer at buf. The data is in the format + indicated by the image descriptor and represents a + source of size width by height. + If sync is TRUE the driver should not return + from this function until it is through reading the data + from buf. Returning when sync + is TRUE indicates that it is safe for the data at buf + to be replaced, freed, or modified. + + +
+ +
+ + typedef int (* QueryImageAttributesFuncPtr)( ScrnInfoPtr pScrn, + int image, short *width, short *height, + int *pitches, int *offsets); + +
+ This function is called to let the driver specify how data for + a particular image of size width + by height should be stored. Sometimes only + the size and corrected width and height are needed. In that + case pitches and offsets are + NULL. The size of the memory required for the image is returned + by this function. The width and + height 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 + pitches and offsets are not NULL, + these will be arrays with as many elements in them as there + are planes in the image 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. + + +
+ + + +The XF86VideoEncodingRec: + +
+ +typedef struct { + int id; + char *name; + unsigned short width, height; + XvRationalRec rate; +} XF86VideoEncodingRec, *XF86VideoEncodingPtr; + + +
+ The XF86VideoEncodingRec 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 + XvQueryEncodings. The id field is + expected to be a unique identifier to allow the client to request a + certain encoding via the XV_ENCODING attribute string. + + +
+ + + +The XF86VideoFormatRec: + +
+ +typedef struct { + char depth; + short class; +} XF86VideoFormatRec, *XF86VideoFormatPtr; + + +
+ This specifies what visuals the video is viewable in. + depth is the depth of the visual (not bpp). + class is the visual class such as + TrueColor, DirectColor or + PseudoColor. Initialization of an adaptor will fail + if none of the visuals on that screen are supported. + + +
+ + + +The XF86AttributeRec: + +
+ +typedef struct { + int flags; + int min_value; + int max_value; + char *name; +} XF86AttributeListRec, *XF86AttributeListPtr; + + +
+ Each adaptor may have an array of these advertising the attributes + for its ports. Currently defined flags are XvGettable + and XvSettable which may be OR'd together indicating that + attribute is gettable or settable by the client. The + min and max field specify the valid range + for the value. Name is a text string describing the + attribute by name. + + +
+ + + + +The XF86ImageRec: + +
+ +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; + + +
+ XF86ImageRec describes how video source data is laid out in memory. + The fields are as follows: + + + + id + + This is a unique descriptor for the format. It is often good to + set this value to the FOURCC for the format when applicable. + + + + type + + This is XvRGB or XvYUV. + + + + byte_order + + This is LSBFirst or MSBFirst. + + + + guid + + This is the Globally Unique IDentifier for the format. When + not applicable, all characters should be NULL. + + + + bits_per_pixel + + 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_. + + + + format + + This is XvPlanar or XvPacked. + + + + num_planes + + The number of planes in planar formats. This should be set to + one for packed formats. + + + + depth + + The significant bits per pixel in RGB formats (analgous to the + depth of a pixmap format). + + + + red_mask + green_mask + blue_mask + + The red, green and blue bitmasks for packed RGB formats. + + + + y_sample_bits + u_sample_bits + v_sample_bits + + The y, u and v sample sizes (in bits). + + + + horz_y_period + horz_u_period + horz_v_period + + The y, u and v sampling periods in the horizontal direction. + + + + vert_y_period + vert_u_period + vert_v_period + + The y, u and v sampling periods in the vertical direction. + + + + component_order + + 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. + + + + scanline_order + + This is XvTopToBottom or XvBottomToTop. + + + + + + + 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. + + +
+ + + + + The Loader + + +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. + + + + Loader Overview + + +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 dlopen(3) service where +available. Such modules are not platform independent, and the semantics +of dlopen() on most systems results in significant +limitations in the use of modules of this type. Support for +dlopen() 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. + + + + + Semi-private Loader Interface + + +The following is the semi-private loader interface that is available to the +XFree86 common layer. + + +
+ + void LoaderInit(void); + +
+ The LoaderInit() 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. + + +
+ +
+ + void LoaderSetPath(const char *path); + +
+ The LoaderSetPath() 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 path 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. + + +
+ +
+ + pointer LoadModule(const char *module, const char *path, + const char **subdirlist, const char **patternlist, + pointer options, const XF86ModReqInfo * modreq, + int *errmaj, int *errmin); + +
+ The LoadModule() function loads the module called + module. 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 module 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: + + + + path + + An optional comma-separated list of module search paths. + When NULL, the default search path is used. + + + + + subdirlist + + An optional NULL terminated list of + subdirectories to search. When NULL, + the default built-in list is used (refer to + stdSubdirs in loadmod.c). + The default list is also substituted for entries in + subdirlist with the value + DEFAULT_LIST. This makes is possible + to augment the default list instead of replacing it. + Subdir elements must be relative, and must not contain + "..". If any violate this requirement, + the load fails. + + + + + patternlist + + An optional NULL 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 NULL, + the default built-in list is used (refer to + stdPatterns in + loadmod.c). The default list is also + substituted for entries in patternlist + with the value DEFAULT_LIST. This + makes it possible to augment the default list instead + of replacing it. + + + + + options + + An optional parameter that is passed to the newly + loaded module's SetupProc function + (if it has one). This argument is normally a + NULL terminated list of + Options, 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 EXTERN_MODULE to tell the + loader not to reject the module when it doesn't find + the standard entry point. + + + + + modreq + + An optional XF86ModReqInfo* 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 SetupProc function. + + + + The XF86ModReqInfo struct is defined + as follows: + +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; + + + The information here is compared against the equivalent + information in the module's + XF86ModuleVersionInfo 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: + + + + majorversion + + Must match the module's majorversion + exactly. + + + + minorversion + + The module's minor version must be + no less than this value. This + comparison is only made if + majorversion is + specified and matches. + + + + patchlevel + + The module's patchlevel must be no + less than this value. This comparison + is only made if + minorversion is + specified and matches. + + + + abiclass + + String must match the module's abiclass + string. + + + + abiversion + + Must be consistent with the module's + abiversion (major equal, minor no + older). + + + + moduleclass + + String must match the module's + moduleclass string. + + + + + + + errmaj + + An optional pointer to a variable holding the major + part or the error code. When provided, + *errmaj is filled in when + LoadModule() fails. + + + + errmin + + Like errmaj, but for the minor part + of the error code. + + + + +
+
+ +
+ + void UnloadModule(pointer mod); + +
+ 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 LoadSubModule() + described below). + + +
+ + + + Module Requirements + + +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 SetupProc +and TearDownProc). + + + +The module information is contained in the +XF86ModuleVersionInfo struct, which is defined as follows: + + +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; + + +The fields are used as follows: + + + + modname + + 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. + + + + + vendor + + The module vendor. This field is for informational purposes + only. + + + + + _modinfo1_ + + 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 MODINFOSTRING1. + + + + + _modinfo2_ + + 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 MODINFOSTRING2. + + + + + xf86version + + The XFree86 version against which the module was compiled. + This is mostly for informational/diagnostic purposes. It + should be initialised to XF86_VERSION_CURRENT, which is + defined in xf86Version.h. + + + + + majorversion + + 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. + + + + + minorversion + + 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. + + + + + patchlevel + + 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. + + + + + abiclass + + 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: + + + + ABI_CLASS_NONE + no class + + + ABI_CLASS_ANSIC + only requires the ANSI C interfaces + + + ABI_CLASS_VIDEODRV + requires the video driver ABI + + + ABI_CLASS_XINPUT + requires the XInput driver ABI + + + ABI_CLASS_EXTENSION + requires the extension module ABI + + + ABI_CLASS_FONT + requires the font module ABI + + + + + + + abiversion + + 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: + + + ABI_ANSIC_VERSION + ABI_VIDEODRV_VERSION + ABI_XINPUT_VERSION + ABI_EXTENSION_VERSION + ABI_FONT_VERSION + + + + + + moduleclass + + 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: + + + MOD_CLASS_NONE + MOD_CLASS_VIDEODRV + MOD_CLASS_XINPUT + MOD_CLASS_FONT + MOD_CLASS_EXTENSION + + + + + + checksum + + Not currently used. + + + + + + +The module version information, and the optional SetupProc +and TearDownProc 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: + + +typedef struct { + XF86ModuleVersionInfo * vers; + ModuleSetupProc setup; + ModuleTearDownProc teardown; +} XF86ModuleData; + + + + +The vers parameter must be initialised to a pointer to a correctly +initialised XF86ModuleVersionInfo struct. The other +two parameter are optional, and should be initialised to +NULL when not required. The other parameters are defined +as + +
+ + typedef pointer (*ModuleSetupProc)(pointer, pointer, int *, int *); + + typedef void (*ModuleTearDownProc)(pointer); + + pointer SetupProc(pointer module, pointer options, + int *errmaj, int *errmin); + +
+ 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 SetupProc if it calls other + loader functions that require a reference to it. The remaining + arguments are those that were passed to the + LoadModule() (or LoadSubModule()), + and are described above. When the SetupProc is + successful it must return a non-NULL value. The + loader checks this, and if it is NULL it unloads + the module and reports the failure to the caller of + LoadModule(). If the SetupProc + does things that need to be undone when the module is unloaded, + it should define a TearDownProc, and return a + pointer that the TearDownProc can use to undo what + has been done. + + + + When a module is loaded multiple times, the SetupProc + is called once for each time it is loaded. + + +
+ +
+ + void TearDownProc(pointer tearDownData); + +
+ When defined, this function is called when the loader unloads a + module. The tearDownData parameter is the return + value of the SetupProc() 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). + + +
+ + + + + Public Loader Interface + + +The following is the Loader interface that is available to any part of +the server, and may also be used from within modules. + + +
+ + pointer LoadSubModule(pointer parent, const char *module, + const char **subdirlist, const char **patternlist, + pointer options, const XF86ModReqInfo * modreq, + int *errmaj, int *errmin); + +
+ This function is like the LoadModule() function + described above, except that the module loaded is registered as a + child of the calling module. The parent 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 + LoaderSetPath(). + + +
+ +
+ + void UnloadSubModule(pointer module); + +
+ This function unloads the module with handle module. + If that module itself has children, they are also unloaded. It is + like UnloadModule(), except that it is safe to use + for unloading child modules. + + +
+ +
+ + pointer LoaderSymbol(const char *symbol); + +
+ This function returns the address of the symbol with name + symbol. This may be used to locate a module entry + point with a known name. + + +
+ +
+ + char **LoaderlistDirs(const char **subdirlist, + const char **patternlist); + +
+ This function returns a NULL terminated list of + canonical modules names for modules found in the default module + search path. The subdirlist and + patternlist 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 NULL. + The returned list should be freed by calling + LoaderFreeDirList() when it is no longer needed. + + +
+ +
+ + void LoaderFreeDirList(char **list); + +
+ This function frees a module list created by + LoaderlistDirs(). + + +
+ +
+ + void LoaderReqSymLists(const char **list0, ...); + +
+ This function allows the registration of required symbols with the + loader. It is normally used by a caller of + LoadSubModule(). If any symbols registered in this + way are found to be unresolved when + LoaderCheckUnresolved() is called then + LoaderCheckUnresolved() will report a failure. + The function takes one or more NULL terminated + lists of symbols. The end of the argument list is indicated by a + NULL argument. + + +
+ +
+ + void LoaderReqSymbols(const char *sym0, ...); + +
+ This function is like LoaderReqSymLists() 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 NULL + argument. + + +
+ +
+ + void LoaderRefSymLists(const char **list0, ...); + +
+ This function allows the registration of possibly unresolved symbols + with the loader. When LoaderCheckUnresolved() 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 NULL terminated + lists of symbols. The end of the argument list is indicated by a + NULL argument. + + +
+ +
+ + void LoaderRefSymbols(const char *sym0, ...); + +
+ This function is like LoaderRefSymLists() 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 NULL + argument. + + +
+ +
+ + int LoaderCheckUnresolved(int delayflag); + +
+ This function checks for unresolved symbols. It generates warnings + for unresolved symbols that have not been registered with + LoaderRefSymLists(), and maps them to a dummy + function. This behaviour may change in future. If unresolved + symbols are found that have been registered with + LoaderReqSymLists() or + LoaderReqSymbols() then this function returns a + non-zero value. If none of these symbols are unresolved the return + value is zero, indicating success. + + + + The delayflag parameter should normally be set to + LD_RESOLV_IFDONE. + + +
+ +
+ + LoaderErrorMsg(const char *name, const char *modname, + int errmaj, int errmin); + +
+ This function prints an error message that includes the text Failed + to load module, the module name modname, a message + specific to the errmaj value, and the value if + errmin. If name is + non-NULL, it is printed as an identifying prefix + to the message (followed by a :). + + +
+ + + + Special Registration Functions + + +The loader contains some functions for registering some classes of modules. +These may be moved out of the loader at some point. + + +
+ + void LoadExtension(ExtensionModule *ext); + +
+ This registers the entry points for the extension identified by + ext. The ExtensionModule struct is + defined as: + + +typedef struct { + InitExtension initFunc; + char * name; + Bool *disablePtr; + InitExtension setupFunc; +} ExtensionModule; + + + +
+ +
+ + void LoadFont(FontModule *font); + +
+ This registers the entry points for the font rasteriser module + identified by font. The FontModule + struct is defined as: + + + typedef struct { + InitFont initFunc; + char * name; + pointer module; +} FontModule; + + + +
+ + + + + + + Helper Functions + + +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. + + + + Functions for printing messages + +
+ + ErrorF(const char *format, ...); + +
+ 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. + + +
+ +
+ + FatalError(const char *format, ...); + +
+ 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. + + +
+ +
+ + xf86ErrorF(const char *format, ...); + +
+ This is like ErrorF(), except that the message is + only printed when the Xserver's verbosity level is set to the + default (1) or higher. It means that the messages + are not printed when the server is started with the + flag. Typically this function would only be + used for continuing messages started with one of the more specialised + functions described below. + + +
+ +
+ + xf86ErrorFVerb(int verb, const char *format, ...); + +
+ Like xf86ErrorF(), except the minimum verbosity + level for which the message is to be printed is given explicitly. + Passing a verb value of zero means the message + is always printed. A value higher than 1 can be + used for information would normally not be needed, but which might + be useful when diagnosing problems. + + +
+ + +
+ + xf86Msg(MessageType type, const char *format, ...); + +
+ This is like xf86ErrorF(), except that the message + is prefixed with a marker determined by the value of + type. The marker is used to indicate the type of + message (warning, error, probed value, config value, etc). Note + the xf86Verbose value is ignored for messages of + type X_ERROR. + + + + The marker values are: + + + + X_PROBED + Value was probed. + + + X_CONFIG + Value was given in the config file. + + + X_DEFAULT + Value is a default. + + + X_CMDLINE + Value was given on the command line. + + + X_NOTICE + Notice. + + + X_ERROR + Error message. + + + X_WARNING + Warning message. + + + X_INFO + Informational message. + + + X_NONE + No prefix. + + + X_NOT_IMPLEMENTED + The message relates to functionality + that is not yetimplemented. + + + + + +
+ +
+ + xf86MsgVerb(MessageType type, int verb, const char *format, ...); + +
+ Like xf86Msg(), but with the verbosity level given + explicitly. + + +
+ +
+ + xf86DrvMsg(int scrnIndex, MessageType type, const char *format, ...); + +
+ This is like xf86Msg() except that the driver's + name (the name field of the + ScrnInfoRec) followed by the + scrnIndex 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 + scrnIndex is negative, this function behaves + exactly like xf86Msg(). + + + + NOTE: This function can only be used after the + ScrnInfoRec and its name field + have been allocated. Normally, this means that it can not be + used before the END of the ChipProbe() function. + Prior to that, use xf86Msg(), providing the + driver's name explicitly. No screen number can be supplied at + that point. + + +
+ +
+ + xf86DrvMsgVerb(int scrnIndex, MessageType type, int verb, + const char *format, ...); + +
+ Like xf86DrvMsg(), but with the verbosity level + given explicitly. + + +
+ + + + + Functions for setting values based on command line and config file + +
+ + Bool xf86SetDepthBpp(ScrnInfoPtr scrp, int depth, int bpp, + + int fbbpp, int depth24flags); + +
+ This function sets the depth, pixmapBPP and bitsPerPixel fields + of the ScrnInfoRec. 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 + ChipPreInit() function. + + + + It requires that the confScreen field of the ScrnInfoRec be + initialised prior to calling it. This is done by the XFree86 + common layer prior to calling ChipPreInit(). + + + + The parameters passed are: + + + + depth + + driver's preferred default depth if no other is given. + If zero, use the overall server default. + + + + bpp + + Same, but for the pixmap bpp. + + + + fbbpp + + Same, but for the framebuffer bpp. + + + + depth24flags + + 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: + + + + NoDepth24Support + No depth 24 formats supported + + + Support24bppFb + 24bpp framebuffer supported + + + Support32bppFb + 32bpp framebuffer supported + + + SupportConvert24to32 + Can convert 24bpp pixmap to 32bpp fb + + + SupportConvert32to24 + Can convert 32bpp pixmap to 24bpp fb + + + ForceConvert24to32 + Force 24bpp pixmap to 32bpp fb conversion + + + ForceConvert32to24 + Force 32bpp pixmap to 24bpp fb conversion + + + + + + + + + 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 ChipPreInit() function should + return FALSE. + + + + 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 depth24flags + 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 depth24flags setting. + + + + On success, the return value is TRUE. On failure + it prints an error message and returns FALSE. + + + + The following fields of the ScrnInfoRec are + initialised by this function: + +
+depth, bitsPerPixel, +display, imageByteOrder, +bitmapScanlinePad, +bitmapScanlineUnit, bitmapBitOrder, +numFormats, formats, +fbFormat. +
+ + +
+ +
+ + void xf86PrintDepthBpp(scrnInfoPtr scrp); + +
+ This function can be used to print out the depth and bpp settings. + It should be called after the final call to + xf86SetDepthBpp(). + + +
+ +
+ + Bool xf86SetWeight(ScrnInfoPtr scrp, rgb weight, rgb mask); + +
+ This function sets the weight, mask, + offset and rgbBits fields of the + ScrnInfoRec. It would normally be called fairly + early in the ChipPreInit() function for + depths > 8bpp. + + + + It requires that the depth and + display fields of the ScrnInfoRec + be initialised prior to calling it. + + + + The parameters passed are: + + + + weight + + driver's preferred default weight if no other is given. + If zero, use the overall server default. + + + + + mask + + Same, but for mask. + + + + + + + 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 ChipPreInit() function should + return FALSE. + + + + On success, this function prints a message showing the weight + values selected, and returns TRUE. + + + + On failure it prints an error message and returns FALSE. + + + + The following fields of the ScrnInfoRec are + initialised by this function: + +
+ weight, + mask, + offset. +
+ + +
+ +
+ + Bool xf86SetDefaultVisual(ScrnInfoPtr scrp, int visual); + +
+ This function sets the defaultVisual field of the + ScrnInfoRec. It would normally be called fairly + early from the ChipPreInit() function. + + + + It requires that the depth and + display fields of the ScrnInfoRec + be initialised prior to calling it. + + + + The parameters passed are: + + + + visual + + driver's preferred default visual if no other is given. + If -1, use the overall server default. + + + + + + + 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 ChipPreInit() function should + return FALSE. + + + + On success, this function prints a message showing the default visual + selected, and returns TRUE. + + + + On failure it prints an error message and returns FALSE. + + +
+ +
+ + Bool xf86SetGamma(ScrnInfoPtr scrp, Gamma gamma); + +
+ This function sets the gamma field of the + ScrnInfoRec. It would normally be called fairly + early from the ChipPreInit() function in cases + where the driver supports gamma correction. + + + + It requires that the monitor field of the + ScrnInfoRec be initialised prior to calling it. + + + + The parameters passed are: + + + + gamma + + driver's preferred default gamma if no other is given. + If zero (< 0.01), use the overall server + default. + + + + + + + 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 ChipPreInit() function should + return FALSE. + + + + On success, this function prints a message showing the gamma + value selected, and returns TRUE. + + + + On failure it prints an error message and returns FALSE. + + +
+ + +
+ + void xf86SetDpi(ScrnInfoPtr pScrn, int x, int y); + +
+ This function sets the xDpi and yDpi + fields of the ScrnInfoRec. The driver can specify + preferred defaults by setting x and y + to non-zero values. The command line option + overrides all other settings. Otherwise, if the + DisplaySize 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. + + +
+ +
+ + void xf86SetBlackWhitePixels(ScrnInfoPtr pScrn); + +
+ This functions sets the blackPixel and + whitePixel fields of the ScrnInfoRec + according to whether or not the command + line options is present. + + +
+ +
+ + const char *xf86GetVisualName(int visual); + +
+ 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, NULL is returned. + + +
+ + + + + Primary Mode functions + + +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. + + +
+ + int xf86ValidateModes(ScrnInfoPtr scrp, DisplayModePtr availModes, + char **modeNames, ClockRangePtr clockRanges, + int *linePitches, int minPitch, int maxPitch, + int pitchInc, int minHeight, int maxHeight, + int virtualX, int virtualY, + unsigned long apertureSize, + LookupModeFlags strategy); + +
+ 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 ChipPreInit() function. + + + + The parameters passed to the function are: + + + + availModes + + List of modes available for the monitor. + + + + modeNames + + List of mode names that the screen is requesting. + + + + clockRanges + + 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 + clockRanges. + + + + linePitches + + List of line pitches supported by the driver. + This is optional and should be NULL when + not used. + + + + minPitch + + Minimum line pitch supported by the driver. This must + be supplied when linePitches is + NULL, and is ignored otherwise. + + + + maxPitch + + Maximum line pitch supported by the driver. This is + required when minPitch is required. + + + + pitchInc + + Granularity of horizontal pitch values as supported by + the chipset. This is expressed in bits. This must be + supplied. + + + + minHeight + + minimum virtual height allowed. If zero, no limit is + imposed. + + + + maxHeight + + maximum virtual height allowed. If zero, no limit is + imposed. + + + + virtualX + + 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. + + + + virtualY + + 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. + + + + apertureSize + + The size (in bytes) of the aperture used to access video + memory. + + + + strategy + + The strategy to use when choosing from multiple modes + with the same name. The options are: + + + + LOOKUP_DEFAULT + ??? + + + LOOKUP_BEST_REFRESH + mode with best refresh rate + + + LOOKUP_CLOSEST_CLOCK + mode with closest matching clock + + + LOOKUP_LIST_ORDER + first usable mode in list + + + + The following options can also be combined (OR'ed) with + one of the above: + + + + LOOKUP_CLKDIV2 + Allow halved clocks + + + LOOKUP_OPTIONAL_TOLERANCES + + Allow missing horizontal sync and/or vertical refresh + ranges in the xorg.conf Monitor section + + + + LOOKUP_OPTIONAL_TOLERANCES 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). + + + + + + + This function requires that the following fields of the + ScrnInfoRec are initialised prior to calling it: + + + + clock[] + + List of discrete clocks (when non-programmable) + + + numClocks + + Number of discrete clocks (when non-programmable) + + + progClock + + Whether the clock is programmable or not + + + monitor + + Pointer to the applicable xorg.conf monitor section + + + fdFormat + + Format of the screen buffer + + + videoRam + + total video memory size (in bytes) + + + maxHValue + + Maximum horizontal timing value allowed + + + maxVValue + + Maximum vertical timing value allowed + + + xInc + + Horizontal timing increment in pixels (defaults to 8) + + + + + + This function fills in the following ScrnInfoRec + fields: + + + + modePool + + A subset of the modes available to the monitor which + are compatible with the driver. + + + + modes + + 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. + + + + virtualX + + The resulting virtual width. + + + + virtualY + + The resulting virtual height. + + + + displayWidth + + The resulting line pitch. + + + + virtualFrom + + Where the virtual size was determined from. + + + + + + + The first stage of this function checks that the + virtualX and virtualY values + supplied (if greater than zero) are consistent with the line pitch + and maxHeight limitations. If not, an error + message is printed, and the return value is -1. + + + + 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 2. If the mode pool ends up being empty, + a warning message is printed, and the return value is + 0. + + + + 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 -1. Otherwise, + the return value is the number of valid modes found + (0 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 -1, the + ChipPreInit() function should return + FALSE. + + + + clockRanges is a linked list of clock ranges + allowed by the driver. If a mode doesn't fit in any of the defined + clockRanges, it is rejected. The first + clockRange that matches all requirements is used. + This structure needs to be initialized to NULL when allocated. + + + + clockRanges contains the following fields: + + + + minClock + maxClock + + The lower and upper mode clock bounds for which the rest + of the clockRange parameters apply. + Since these are the mode clocks, they are not scaled + with the ClockMulFactor and + ClockDivFactor. It is up to the driver + to adjust these values if they depend on the clock + scaling factors. + + + + clockIndex + + (not used yet) -1 for programmable clocks + + + + interlaceAllowed + + TRUE if interlacing is allowed for this + range + + + + doubleScanAllowed + + TRUE if doublescan or multiscan is allowed + for this range + + + + ClockMulFactor + ClockDivFactor + + Scaling factors that are applied to the mode clocks ONLY + before selecting a clock index (when there is no + programmable clock) or a SynthClock + 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 2:1 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, ClockMulFactor=1 and + ClockDivFactor=2. This means that the + clock used for clock selection (ie, determining the + correct clock index from the list of discrete clocks) + or for the SynthClock field in case of + a programmable clock is: (mode->Clock * + ClockMulFactor) / ClockDivFactor. + + + + PrivFlags + + This field is copied into the + mode->PrivFlags field when this + clockRange is selected by + xf86ValidateModes(). 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 INT). + + + + + + Note that the mode->SynthClock field is always + filled in by xf86ValidateModes(): 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: + + + mode->SynthClock = (mode->Clock * ClockMulFactor) / ClockDivFactor + + + +
+ +
+ + void xf86PruneDriverModes(ScrnInfoPtr scrp); + +
+ This function deletes modes in the modes field of the + ScrnInfoRec that have been marked as invalid. + This is normally run after having run + xf86ValidateModes() for the last time. For each + mode that is deleted, a warning message is printed out indicating + the reason for it being deleted. + + +
+ +
+ + void xf86SetCrtcForModes(ScrnInfoPtr scrp, int adjustFlags); + +
+ This function fills in the Crtc* fields for all + the modes in the modes field of the + ScrnInfoRec. The adjustFlags + parameter determines how the vertical CRTC values are scaled for + interlaced modes. They are halved if it is + INTERLACE_HALVE_V. The vertical CRTC values are + doubled for doublescan modes, and are further multiplied by the + VScan value. + + + + This function is normally called after calling + xf86PruneDriverModes(). + + +
+ +
+ + void xf86PrintModes(ScrnInfoPtr scrp); + +
+ 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 + xf86SetCrtcForModes(). + + +
+ + + + + Secondary Mode functions + + +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. + + +
+ + int xf86GetNearestClock(ScrnInfoPtr scrp, int freq, Bool allowDiv2, + int *divider); + +
+ This function returns the index of the closest clock to the + frequency freq given (in kHz). It assumes that + the number of clocks is greater than zero. It requires that the + numClocks and clock fields of the + ScrnInfoRec are initialised. The + allowDiv2 field determines if the clocks can be + halved. The *divider return value indicates + whether clock division is used when determining the clock returned. + + + + This function is only for non-programmable clocks. + + +
+ +
+ + const char *xf86ModeStatusToString(ModeStatus status); + +
+ This function converts the status value to a + descriptive printable string. + + +
+ +
+ + ModeStatus xf86LookupMode(ScrnInfoPtr scrp, DisplayModePtr modep, + ClockRangePtr clockRanges, LookupModeFlags strategy); + +
+ This function takes a pointer to a mode with the name filled in, + and looks for a mode in the modePool list which + matches. The parameters of the matching mode are filled in to + *modep. The clockRanges and + strategy parameters are as for the + xf86ValidateModes() function above. + + + + This function requires the modePool, + clock[], numClocks and + progClock fields of the ScrnInfoRec + to be initialised before being called. + + + + The return value is MODE_OK if a mode was found. + Otherwise it indicates why a matching mode could not be found. + + +
+ +
+ + ModeStatus xf86InitialCheckModeForDriver(ScrnInfoPtr scrp, + DisplayModePtr mode, ClockRangePtr clockRanges, + LookupModeFlags strategy, int maxPitch, + int virtualX, int virtualY); + +
+ This function checks the passed mode against some basic driver + constraints. Apart from the ones passed explicitly, the + maxHValue and maxVValue fields of + the ScrnInfoRec are also used. If the + ValidMode field of the ScrnInfoRec + 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 MODE_OK. Otherwise the return value indicates + which constraint wasn't met. + + +
+ +
+ + void xf86DeleteMode(DisplayModePtr *modeList, DisplayModePtr mode); + +
+ This function deletes the mode given from the + modeList. It never prints any messages, so it is + up to the caller to print a message if required. + + +
+ + + + Functions for handling strings and tokens + + + 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: + + +typedef struct { + int token; + const char * name; +} SymTabRec, *SymTabPtr; + + + + + A table is an initialised array of SymTabRec. 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 + token value of -1 and + NULL for the name. + + +
+ + const char *xf86TokenToString(SymTabPtr table, int token); + +
+ This function returns the first string in table + that matches token. If no match is found, + NULL is returned (NOTE, older versions of this + function would return the string "unknown" when no match is found). + + +
+ +
+ + int xf86StringToToken(SymTabPtr table, const char *string); + +
+ This function returns the first token in table + that matches string. The + xf86NameCmp() function is used to determine the + match. If no match is found, -1 is returned. + + +
+ + + + + Functions for finding which config file entries to use + + + These functions can be used to select the appropriate config file + entries that match the detected hardware. They are described above + in the Probe and + Available Functions sections. + + + + + + Probing discrete clocks on old hardware + + + The xf86GetClocks() function may be used to assist + in finding the discrete pixel clock values on older hardware. + + +
+ + void xf86GetClocks(ScrnInfoPtr pScrn, int num, + Bool (*ClockFunc)(ScrnInfoPtr, int), + void (*ProtectRegs)(ScrnInfoPtr, Bool), + void (*BlankScreen)(ScrnInfoPtr, Bool), + int vertsyncreg, int maskval, int knownclkindex, + int knownclkvalue); + +
+ This function uses a comparative sampling method to measure the + discrete pixel clock values. The number of discrete clocks to + measure is given by num. clockFunc + is a function that selects the n'th clock. It + should also save or restore any state affected by programming the + clocks when the index passed is CLK_REG_SAVE or + CLK_REG_RESTORE. ProtectRegs is + a function that does whatever is required to protect the hardware + state while selecting a new clock. BlankScreen + is a function that blanks the screen. vertsyncreg + and maskval are the register and bitmask to + check for the presence of vertical sync pulses. + knownclkindex and knownclkvalue + 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 pScrn->numClocks, + and the probed clocks are set in the pScrn->clock[] + array. All of the clock values are in units of kHz. + + +
+ +
+ + void xf86ShowClocks(ScrnInfoPtr scrp, MessageType from); + +
+ Print out the pixel clocks scrp->clock[]. + from indicates whether the clocks were probed + or from the config file. + + +
+ + + + Other helper functions + +
+ + Bool xf86IsUnblank(int mode); + +
+ Returns TRUE when the screen saver mode specified + by mode requires the screen be unblanked, + and FALSE otherwise. The screen saver modes that + require blanking are SCREEN_SAVER_ON and + SCREEN_SAVER_CYCLE, and the screen saver modes that + require unblanking are SCREEN_SAVER_OFF and + SCREEN_SAVER_FORCER. Drivers may call this helper + from their SaveScreen() function to interpret the + screen saver modes. + + +
+ + + + + The vgahw module + + +The vgahw modules provides an interface for saving, restoring and +programming the standard VGA registers, and for handling VGA colourmaps. + + + + Data Structures + + + The public data structures used by the vgahw module are + vgaRegRec and vgaHWRec. They are + defined in vgaHW.h. + + + + + + General vgahw Functions + +
+ + Bool vgaHWGetHWRec(ScrnInfoPtr pScrn); + +
+ This function allocates a vgaHWRec structure, and + hooks it into the ScrnInfoRec's + privates. Like all information hooked into the + privates, it is persistent, and only needs to be + allocated once per screen. This function should normally be called + from the driver's ChipPreInit() function. The + vgaHWRec is zero-allocated, and the following + fields are explicitly initialised: + + + + ModeReg.DAC[] + initialised with a default colourmap + + + ModeReg.Attribute[0x11] + initialised with the default overscan index + + + ShowOverscan + initialised according to the "ShowOverscan" option + + + paletteEnabled + initialised to FALSE + + + cmapSaved + initialised to FALSE + + + pScrn + initialised to pScrn + + + + + + In addition to the above, vgaHWSetStdFuncs() is + called to initialise the register access function fields with the + standard VGA set of functions. + + + + Once allocated, a pointer to the vgaHWRec can be + obtained from the ScrnInfoPtr with the + VGAHWPTR(pScrn) macro. + + +
+ +
+ + void vgaHWFreeHWRec(ScrnInfoPtr pScrn); + +
+ This function frees a vgaHWRec structure. It + should be called from a driver's ChipFreeScreen() + function. + + +
+ +
+ + Bool vgaHWSetRegCounts(ScrnInfoPtr pScrn, int numCRTC, + int numSequencer, int numGraphics, int numAttribute); + +
+ 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 + vgaHWSave() and vgaHWRestore(). + This function should be called after a vgaHWRec + has been allocated with vgaHWGetHWRec(). The + default values are defined in vgaHW.h as follows: + + +#define VGA_NUM_CRTC 25 +#define VGA_NUM_SEQ 5 +#define VGA_NUM_GFX 9 +#define VGA_NUM_ATTR 21 + + + +
+ +
+ + Bool vgaHWCopyReg(vgaRegPtr dst, vgaRegPtr src); + +
+ This function copies the contents of the VGA saved registers in + src to dst. Note that it isn't + possible to simply do this with memcpy() (or + similar). This function returns TRUE unless there + is a problem allocating space for the CRTC and + related fields in dst. + + +
+ +
+ + void vgaHWSetStdFuncs(vgaHWPtr hwp); + +
+ This function initialises the register access function fields of + hwp with the standard VGA set of functions. This + is called by vgaHWGetHWRec(), 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 + hwp->PIOOffset is initialised with + offset, 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 + vgaHWGetHWRec(). (Note: the PIOOffset functionality + is present in XFree86 4.1.0 and later.) + + +
+ +
+ + void vgaHWSetMmioFuncs(vgaHWPtr hwp, CARD8 *base, int offset); + +
+ This function initialised the register access function fields of + hwp with a generic MMIO set of functions. + hwp->MMIOBase is initialised with + base, which must be the virtual address that the + start of MMIO area is mapped to. hwp->MMIOOffset + is initialised with offset, 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. + + +
+ +
+ + Bool vgaHWMapMem(ScrnInfoPtr pScrn); + +
+ This function maps the VGA memory window. It requires that the + vgaHWRec be allocated. If a driver requires + non-default MapPhys or MapSize + settings (the physical location and size of the VGA memory window) + then those fields of the vgaHWRec must be initialised + before calling this function. Otherwise, this function initialiases + the default values of 0xA0000 for + MapPhys and (64 * 1024) for + MapSize. This function must be called before + attempting to save or restore the VGA state. If the driver doesn't + call it explicitly, the vgaHWSave() and + vgaHWRestore() functions may call it if they need + to access the VGA memory (in which case they will also call + vgaHWUnmapMem() to unmap the VGA memory before + exiting). + + +
+ +
+ + void vgaHWUnmapMem(ScrnInfoPtr pScrn); + +
+ This function unmaps the VGA memory window. It must only be called + after the memory has been mapped. The Base field + of the vgaHWRec field is set to NULL + to indicate that the memory is no longer mapped. + + +
+ +
+ + void vgaHWGetIOBase(vgaHWPtr hwp); + +
+ This function initialises the IOBase field of the + vgaHWRec. This function must be called before + using any other functions that access the video hardware. + + + + A macro VGAHW_GET_IOBASE() is also available in + vgaHW.h that returns the I/O base, and this may + be used when the vgahw module is not loaded (for example, in the + ChipProbe() function). + + +
+ +
+ + void vgaHWUnlock(vgaHWPtr hwp); + +
+ This function unlocks the VGA CRTC[0-7] registers, + and must be called before attempting to write to those registers. + + +
+ +
+ + void vgaHWLock(vgaHWPtr hwp); + +
+ This function locks the VGA CRTC[0-7] registers. + + +
+ +
+ + void vgaHWEnable(vgaHWPtr hwp); + +
+ This function enables the VGA subsystem. (Note, this function is + present in XFree86 4.1.0 and later.). + + +
+ +
+ + void vgaHWDisable(vgaHWPtr hwp); + +
+ This function disables the VGA subsystem. (Note, this function is + present in XFree86 4.1.0 and later.). + + +
+ +
+ + void vgaHWSave(ScrnInfoPtr pScrn, vgaRegPtr save, int flags); + +
+ This function saves the VGA state. The state is written to the + vgaRegRec pointed to by save. + flags is set to one or more of the following flags + ORed together: + + + + VGA_SR_MODE + the mode setting registers are saved + + + VGA_SR_FONTS + the text mode font/text data is saved + + + VGA_SR_CMAP + the colourmap (LUT) is saved + + + VGA_SR_ALL + all of the above are saved + + + + + + The vgaHWRec and its IOBase fields + must be initialised before this function is called. If + VGA_SR_FONTS is set in flags, the + VGA memory window must be mapped. If it isn't then + vgaHWMapMem() will be called to map it, and + vgaHWUnmapMem() will be called to unmap it + afterwards. vgaHWSave() uses the three functions + below in the order vgaHWSaveColormap(), + vgaHWSaveMode(), vgaHWSaveFonts() 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. + + +
+ +
+ + void vgaHWSaveMode(ScrnInfoPtr pScrn, vgaRegPtr save); + +
+ This function saves the VGA mode registers. They are saved to + the vgaRegRec pointed to by save. + The registers saved are: + + + MiscOut + CRTC[0-0x18] + Attribute[0-0x14] + Graphics[0-8] + Sequencer[0-4] + + + + + The number of registers actually saved may be modified by a prior call + to vgaHWSetRegCounts(). + + +
+ +
+ + void vgaHWSaveFonts(ScrnInfoPtr pScrn, vgaRegPtr save); + +
+ 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 + vgaHWMapMem() 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. + + +
+ +
+ + void vgaHWSaveColormap(ScrnInfoPtr pScrn, vgaRegPtr save); + +
+ 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. + + +
+ +
+ + void vgaHWRestore(ScrnInfoPtr pScrn, vgaRegPtr restore, int flags); + +
+ This function programs the VGA state. The state programmed is + that contained in the vgaRegRec pointed to by + restore. flags is the same + as described above for the vgaHWSave() function. + + + + The vgaHWRec and its IOBase fields + must be initialised before this function is called. If + VGA_SR_FONTS is set in flags, the + VGA memory window must be mapped. If it isn't then + vgaHWMapMem() will be called to map it, and + vgaHWUnmapMem() will be called to unmap it + afterwards. vgaHWRestore() uses the three functions + below in the order vgaHWRestoreFonts(), + vgaHWRestoreMode(), + vgaHWRestoreColormap() 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. + + +
+ +
+ + void vgaHWRestoreMode(ScrnInfoPtr pScrn, vgaRegPtr restore); + +
+ This function restores the VGA mode registers. They are restored + from the data in the vgaRegRec pointed to by + restore. The registers restored are: + + + MiscOut + CRTC[0-0x18] + Attribute[0-0x14] + Graphics[0-8] + Sequencer[0-4] + + + + + The number of registers actually restored may be modified by a prior call + to vgaHWSetRegCounts(). + + +
+ +
+ + void vgaHWRestoreFonts(ScrnInfoPtr pScrn, vgaRegPtr restore); + +
+ This function restores the text mode font and text data to the + video memory. The VGA memory window must be mapped with + vgaHWMapMem() 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. + + +
+ +
+ + void vgaHWRestoreColormap(ScrnInfoPtr pScrn, vgaRegPtr restore); + +
+ This function restores the VGA colourmap (LUT). + + +
+ +
+ + void vgaHWInit(ScrnInfoPtr pScrn, DisplayModePtr mode); + +
+ This function fills in the vgaHWRec's + ModeReg field with the values appropriate for + programming the given video mode. It requires that the + ScrnInfoRec's depth field is + initialised, which determines how the registers are programmed. + + +
+ +
+ + void vgaHWSeqReset(vgaHWPtr hwp, Bool start); + +
+ Do a VGA sequencer reset. If start is TRUE, the + reset is started. If start is FALSE, the reset + is ended. + + +
+ +
+ + void vgaHWProtect(ScrnInfoPtr pScrn, Bool on); + +
+ This function protects VGA registers and memory from corruption + during loads. It is typically called with on set to + TRUE before programming, and with on set to + FALSE after programming. + + +
+ +
+ + Bool vgaHWSaveScreen(ScreenPtr pScreen, int mode); + +
+ This function blanks and unblanks the screen. It is blanked when + mode is SCREEN_SAVER_ON or + SCREEN_SAVER_CYCLE, and unblanked when + mode is SCREEN_SAVER_OFF or + SCREEN_SAVER_FORCER. + + +
+ +
+ + void vgaHWBlankScreen(ScrnInfoPtr pScrn, Bool on); + +
+ This function blanks and unblanks the screen. It is blanked when + on is FALSE, and unblanked when + on is TRUE. This function is + provided for use in cases where the ScrnInfoRec + can't be derived from the ScreenRec (while probing + for clocks, for example). + + +
+ + + + + VGA Colormap Functions + + + The vgahw module uses the standard colormap support (see the + Colormap Handling section. This is initialised + with the following function: + +
+ + Bool vgaHWHandleColormaps(ScreenPtr pScreen); + +
+ + + + + + VGA Register Access Functions + + + The vgahw module abstracts access to the standard VGA registers by + using a set of functions held in the vgaHWRec. When + the vgaHWRec 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 vgaHWRec function + pointers can be initialised to these by calling the + vgaHWSetMmioFuncs() function described above. Some + drivers/platforms may require a different set of functions for VGA + access. The access functions are described here. + + + +
+ + void writeCrtc(vgaHWPtr hwp, CARD8 index, CARD8 value); + +
+ Write value to CRTC register index. + + +
+ +
+ + CARD8 readCrtc(vgaHWPtr hwp, CARD8 index); + +
+ Return the value read from CRTC register index. + + +
+ +
+ + void writeGr(vgaHWPtr hwp, CARD8 index, CARD8 value); + +
+ Write value to Graphics Controller register + index. + + +
+ +
+ + CARD8 readGR(vgaHWPtr hwp, CARD8 index); + +
+ Return the value read from Graphics Controller register + index. + + +
+ +
+ + void writeSeq(vgaHWPtr hwp, CARD8 index, CARD8, value); + +
+ Write value to Sequencer register + index. + + +
+ +
+ + CARD8 readSeq(vgaHWPtr hwp, CARD8 index); + +
+ Return the value read from Sequencer register index. + + +
+ +
+ + void writeAttr(vgaHWPtr hwp, CARD8 index, CARD8, value); + +
+ Write value to Attribute Controller register + index. When writing out the index value this + function should set bit 5 (0x20) according to the + setting of hwp->paletteEnabled in order to + preserve the palette access state. It should be cleared when + hwp->paletteEnabled is TRUE + and set when it is FALSE. + + +
+ +
+ + CARD8 readAttr(vgaHWPtr hwp, CARD8 index); + +
+ Return the value read from Attribute Controller register + index. When writing out the index value this + function should set bit 5 (0x20) according to the + setting of hwp->paletteEnabled in order to + preserve the palette access state. It should be cleared when + hwp->paletteEnabled is TRUE + and set when it is FALSE. + + +
+ +
+ + void writeMiscOut(vgaHWPtr hwp, CARD8 value); + +
+ Write value to the Miscellaneous Output register. + + +
+ +
+ + CARD8 readMiscOut(vgwHWPtr hwp); + +
+ Return the value read from the Miscellaneous Output register. + + +
+ +
+ + void enablePalette(vgaHWPtr hwp); + +
+ Clear the palette address source bit in the Attribute Controller + index register and set hwp->paletteEnabled to + TRUE. + + +
+ +
+ + void disablePalette(vgaHWPtr hwp); + +
+ Set the palette address source bit in the Attribute Controller + index register and set hwp->paletteEnabled to + FALSE. + + +
+ +
+ + void writeDacMask(vgaHWPtr hwp, CARD8 value); + +
+ Write value to the DAC Mask register. + + +
+ +
+ + CARD8 readDacMask(vgaHWptr hwp); + +
+ Return the value read from the DAC Mask register. + + +
+ +
+ + void writeDacReadAddress(vgaHWPtr hwp, CARD8 value); + +
+ Write value to the DAC Read Address register. + + +
+ +
+ + void writeDacWriteAddress(vgaHWPtr hwp, CARD8 value); + +
+ Write value to the DAC Write Address register. + + +
+ +
+ + void writeDacData(vgaHWPtr hwp, CARD8 value); + +
+ Write value to the DAC Data register. + + +
+ +
+ + CARD8 readDacData(vgaHWptr hwp); + +
+ Return the value read from the DAC Data register. + + +
+ +
+ + CARD8 readEnable(vgaHWptr hwp); + +
+ Return the value read from the VGA Enable register. (Note: This + function is present in XFree86 4.1.0 and later.) + + +
+ +
+ + void writeEnable(vgaHWPtr hwp, CARD8 value); + +
+ Write value to the VGA Enable register. (Note: This + function is present in XFree86 4.1.0 and later.) + + +
+ + + + + Some notes about writing a driver + + NOTE: some parts of this are not up to date + + +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. + + + + Include files + + + All drivers normally include the following headers: + + "xf86.h" + "xf86_OSproc.h" + "xf86_ansic.h" + "xf86Resources.h" + + Wherever inb/outb (and related things) are used the following should be + included: + + "compiler.h" + + Note: in drivers, this must be included after "xf86_ansic.h". + + + + Drivers that need to access PCI vendor/device definitions need this: + + "xf86PciInfo.h" + + + + + Drivers that need to access the PCI config space need this: + + "xf86Pci.h" + + + + + Drivers using the mi banking wrapper need: + + + "mibank.h" + + + + + Drivers that initialise a SW cursor need this: + + "mipointer.h" + + + + + All drivers implementing backing store need this: + + "mibstore.h" + + + + + All drivers using the mi colourmap code need this: + + "micmap.h" + + + + + If a driver uses the vgahw module, it needs this: + + "vgaHW.h" + + + + + Drivers supporting VGA or Hercules monochrome screens need: + + "xf1bpp.h" + + + + + Drivers supporting VGA or EGC 16-colour screens need: + + "xf4bpp.h" + + + + + Drivers using cfb need: + + #define PSZ 8 + #include "cfb.h" + #undef PSZ + + + + + Drivers supporting bpp 16, 24 or 32 with cfb need one or more of: + + "cfb16.h" + "cfb24.h" + "cfb32.h" + + + + + The driver's own header file: + + "zzz.h" + + + + + Drivers must NOT include the following: + + + "xf86Priv.h" + "xf86Privstr.h" + "xf86_libc.h" + "xf86_OSlib.h" + "Xos.h" + any OS header + + + + + + + Data structures and initialisation + + + + The following macros should be defined: + +#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> + + + + NOTE: ZZZ_DRIVER_NAME should match the name of the + driver module without things like the "lib" prefix, the "_drv" suffix + or filename extensions. + + + + + + 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). + +DriverRec ZZZ = { + VERSION, + ZZZ_DRIVER_NAME, + ZZZIdentify, + ZZZProbe, + ZZZAvailableOptions, + NULL, + 0 +}; + + + + + + Define list of supported chips and their matching ID: + +static SymTabRec ZZZChipsets[] = { + { PCI_CHIP_ZZZ1234, "zzz1234a" }, + { PCI_CHIP_ZZZ5678, "zzz5678a" }, + { -1, NULL } +}; + + + + 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 enum type. + + + + + + If the driver uses the xf86MatchPciInstances() + helper (recommended for drivers that support PCI cards) a list that + maps PCI IDs to chip IDs and fixed resources must be defined: + +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 } +} + + + + + + + Define the XF86ModuleVersionInfo struct for the + driver. This is required for the dynamically loaded version: + +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} +}; + + + + + + + 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 "zzz.h" file, something like: + +typedef struct { + type1 field1; + type2 field2; + int fooHack; + Bool pciRetry; + Bool noAccel; + Bool hwCursor; + CloseScreenProcPtr CloseScreen; + OptionInfoPtr Options; + ... +} ZZZRec, *ZZZPtr; + + + + + + + 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. + + +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 } +}; + + + + + + + + Functions + + + + SetupProc + + + For dynamically loaded modules, a ModuleData + variable is required. It is should be the name of the driver + prepended to "ModuleData". A Setup() function is + also required, which calls xf86AddDriver() to add + the driver to the main list of drivers. + + + +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; + } +} + + + + + GetRec, FreeRec + + + A function is usually required to allocate the driver's + screen-specific data structure and hook it into the + ScrnInfoRec's driverPrivate field. + The ScrnInfoRec's driverPrivate is + initialised to NULL, so it is easy to check if the + initialisation has already been done. After allocating it, initialise + the fields. By using xnfcalloc() to do the allocation + it is zeroed, and if the allocation fails the server exits. + + + + 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. + + + +static Bool +ZZZGetRec(ScrnInfoPtr pScrn) +{ + if (pScrn->driverPrivate != NULL) + return TRUE; + pScrn->driverPrivate = xnfcalloc(sizeof(ZZZRec), 1); + /* Initialise as required */ + ... + return TRUE; +} + + + + Define a macro in "zzz.h" which gets a pointer to + the ZZZRec when given pScrn: + + +#define ZZZPTR(p) ((ZZZPtr)((p)->driverPrivate)) + + + + + Define a function to free the above, setting it to NULL + once it has been freed: + + +static void +ZZZFreeRec(ScrnInfoPtr pScrn) +{ + if (pScrn->driverPrivate == NULL) + return; + xfree(pScrn->driverPrivate); + pScrn->driverPrivate = NULL; +} + + + + + + Identify + + + Define the Identify() 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: + + +static void +ZZZIdentify(int flags) +{ + xf86PrintChipsets(ZZZ_NAME, "driver for ZZZ Tech chipsets", + ZZZChipsets); +} + + + + + + Probe + + + Define the Probe() 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 ScrnInfoRec. 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 ScrnInfoRec initialisations. + Don't allocate any new data structures. + + + + This function is mandatory. + + + + NOTE: The xf86DrvMsg() functions cannot be used from + the Probe. + + + +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; + + + + + AvailableOptions + + + Define the AvailableOptions() 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. + + + + + PreInit + + + Define the PreInit() 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 + ScrnInfoRec 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: + + + The PreInit() function is only called once + during the life of the X server (at the start of the first + generation). + + + + 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 ScrnInfoRec's privates + field should be allocated here, but data that hooks into the + ScreenRec's devPrivates field + should not be allocated here. The driverPrivate + field should also be allocated here. + + + + Although the ScrnInfoRec has been allocated + before this function is called, the ScreenRec + has not been allocated. That means that things requiring it + cannot be used in this function. + + + + Very little of the ScrnInfoRec has been + initialised when this function is called. It is important to + get the order of doing things right in this function. + + + + + + +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; +} + + + + + MapMem, UnmapMem + + + 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. + + + +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; +} + + + + + Save, Restore + + + Define functions to save and restore the original video state. These + functions are not mandatory, but are often useful. + + + +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. + */ + ... +} + + + + + ModeInit + + + Define a function to initialise a new video mode. This function isn't + mandatory, but is often useful. + + + +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. + */ + ... +} + + + + + ScreenInit + + + Define the ScreenInit() function. This is called + at the start of each server generation, and should fill in as much + of the ScreenRec 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 ScreenRec (pScreen) is + passed to this driver, but it and the + ScrnInfoRecs are not yet hooked into each + other. This means that in this function, and functions it + calls, one cannot be found from the other. + + + +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; +} + + + + + SwitchMode + + + Define the SwitchMode() function if mode switching + is supported by the driver. + + + +static Bool +ZZZSwitchMode(int scrnIndex, DisplayModePtr mode, int flags) +{ + return ZZZModeInit(xf86Screens[scrnIndex], mode); +} + + + + + AdjustFrame + + + Define the AdjustFrame() function if the driver + supports this. + + + +static void +ZZZAdjustFrame(int scrnIndex, int x, int y, int flags) +{ + /* Adjust the viewport */ +} + + + + + EnterVT, LeaveVT + + + Define the EnterVT() and LeaveVT() + functions. + + + + These functions are mandatory. + + + +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); +} + + + + + CloseScreen + + + Define the CloseScreen() function: + + + + This function is mandatory. Note that it unwraps the previously + wrapped pScreen->CloseScreen, and finishes by + calling it. + + + +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); +} + + + + + SaveScreen + + + Define the SaveScreen() function (the screen + blanking function). When using the vgahw module, this will typically + be: + + +static Bool +ZZZSaveScreen(ScreenPtr pScreen, int mode) +{ + return vgaHWSaveScreen(pScreen, mode); +} + + + + + This function is mandatory. Before modifying any hardware register + directly this function needs to make sure that the Xserver is active + by checking if pScrn is non-NULL and for + pScrn->vtSema == TRUE. + + + + + FreeScreen + + + Define the FreeScreen() function. This function + is optional. It should be defined if the ScrnInfoRec + driverPrivate 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 CloseScreen() function. + + + +static void +ZZZFreeScreen(int scrnIndex, int flags) +{ + /* + * If the vgahw module is used vgaHWFreeHWRec() would be called + * here. + */ + ZZZFreeRec(xf86Screens[scrnIndex]); +} + + + + + + + + + +
diff --git a/xorg-server/hw/xfree86/doc/sgml/Makefile.am b/xorg-server/hw/xfree86/doc/sgml/Makefile.am index 09b64f7b0..7756c47ac 100644 --- a/xorg-server/hw/xfree86/doc/sgml/Makefile.am +++ b/xorg-server/hw/xfree86/doc/sgml/Makefile.am @@ -1,54 +1,31 @@ -# 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 $@ - $(AM_V_GEN)$(MAKE_TEXT) $< - -.sgml.ps: - @rm -f $@ - $(AM_V_GEN)$(MAKE_PS) $< - -.ps.pdf: - @rm -f $@ - $(AM_V_GEN)$(MAKE_PDF) $< - -.sgml.html: - @rm -f $@ - $(AM_V_GEN)$(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) +# 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. + +XML_FILES = DESIGN.xml + +include ../../../../doc/xml/xmlrules.in + +if ENABLE_DEVEL_DOCS +noinst_DATA = $(BUILT_DOC_FILES) +endif +CLEANFILES = $(CLEAN_DOC_FILES) + +EXTRA_DIST = $(XML_FILES) -- cgit v1.2.3