xorg.conf.man 73.9 KB
Newer Older
Egbert Eich's avatar
Egbert Eich committed
1 2 3 4
.\" shorthand for double quote that works everywhere.
.ds q \N'34'
.TH __xconfigfile__ __filemansuffix__ __vendorversion__
.SH NAME
5 6
__xconfigfile__ and __xconfigdir__ \- configuration files for
__xservername__ X server
Egbert Eich's avatar
Egbert Eich committed
7 8 9 10
.SH INTRODUCTION
.B __xservername__
supports several mechanisms for supplying/obtaining configuration and
run-time parameters: command line options, environment variables, the
11 12 13 14 15 16 17 18 19 20 21
__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.
Egbert Eich's avatar
Egbert Eich committed
22 23 24
.SH DESCRIPTION
.B __xservername__
uses a configuration file called
Branden Robinson's avatar
Branden Robinson committed
25
.I __xconfigfile__
26 27 28 29
and files ending in the suffix
.I .conf
from the directory
.I __xconfigdir__
Branden Robinson's avatar
Branden Robinson committed
30
for its initial setup.
31 32 33
The
.I __xconfigfile__
configuration file is searched for in the following places when the
Branden Robinson's avatar
Branden Robinson committed
34
server is started as a normal user:
Egbert Eich's avatar
Egbert Eich committed
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
.PP
.RS 4
.nf
.IR /etc/X11/ <cmdline>
.IR __projectroot__/etc/X11/ <cmdline>
.IB /etc/X11/ $XORGCONFIG
.IB __projectroot__/etc/X11/ $XORGCONFIG
.I /etc/X11/__xconfigfile__
.I /etc/__xconfigfile__
.IR __projectroot__/etc/X11/__xconfigfile__. <hostname>
.I __projectroot__/etc/X11/__xconfigfile__
.IR __projectroot__/lib/X11/__xconfigfile__. <hostname>
.I __projectroot__/lib/X11/__xconfigfile__
.fi
.RE
.PP
where
.I <cmdline>
Branden Robinson's avatar
Branden Robinson committed
53
is a relative path (with no \(lq..\(rq components) specified with the
Egbert Eich's avatar
Egbert Eich committed
54 55 56
.B \-config
command line option,
.B $XORGCONFIG
Branden Robinson's avatar
Branden Robinson committed
57
is the relative path (with no \(lq..\(rq components) specified by that
Egbert Eich's avatar
Egbert Eich committed
58 59
environment variable, and
.I <hostname>
Branden Robinson's avatar
Branden Robinson committed
60
is the machine's hostname as reported by
61
.BR gethostname (__libmansuffix__).
Egbert Eich's avatar
Egbert Eich committed
62
.PP
Branden Robinson's avatar
Branden Robinson committed
63
When the __xservername__ server is started by the \(lqroot\(rq user, the config file
Egbert Eich's avatar
Egbert Eich committed
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
search locations are as follows:
.PP
.RS 4
.nf
<cmdline>
.IR /etc/X11/ <cmdline>
.IR __projectroot__/etc/X11/ <cmdline>
.B $XORGCONFIG
.IB /etc/X11/ $XORGCONFIG
.IB __projectroot__/etc/X11/ $XORGCONFIG
.I /etc/X11/__xconfigfile__
.I /etc/__xconfigfile__
.IR __projectroot__/etc/X11/__xconfigfile__. <hostname>
.I __projectroot__/etc/X11/__xconfigfile__
.IR __projectroot__/lib/X11/__xconfigfile__. <hostname>
.I __projectroot__/lib/X11/__xconfigfile__
.fi
.RE
.PP
where
.I <cmdline>
is the path specified with the
.B \-config
command line option (which may be absolute or relative),
.B $XORGCONFIG
is the path specified by that
environment variable (absolute or relative),
.B $HOME
is the path specified by that environment variable (usually the home
directory), and
.I <hostname>
Branden Robinson's avatar
Branden Robinson committed
95
is the machine's hostname as reported by
96
.BR gethostname (__libmansuffix__).
Egbert Eich's avatar
Egbert Eich committed
97
.PP
98
Additional configuration files are searched for in the following
99
directories when the server is started as a normal user:
100 101 102
.PP
.RS 4
.nf
103
.IR /etc/X11/ <cmdline>
104
.IR __sysconfdir__/X11/ <cmdline>
105
.I /etc/X11/__xconfigdir__
106
.I __sysconfdir__/X11/__xconfigdir__
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122
.fi
.RE
.PP
where
.I <cmdline>
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
<cmdline>
.IR /etc/X11/ <cmdline>
123
.IR __sysconfdir__/X11/ <cmdline>
124
.I /etc/X11/__xconfigdir__
125
.I __sysconfdir__/X11/__xconfigdir__
126 127 128
.fi
.RE
.PP
129 130 131 132 133 134
where
.I <cmdline>
is the path specified with the
.B \-configdir
command line option (which may be absolute or relative).
.PP
135 136 137 138 139 140 141 142 143 144 145 146
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
Egbert Eich's avatar
Egbert Eich committed
147
The
Branden Robinson's avatar
Branden Robinson committed
148
.I __xconfigfile__
149 150 151
and
.I __xconfigdir__
files are composed of a number of sections which may be present in any order,
152
or omitted to use default configuration values.
Branden Robinson's avatar
Branden Robinson committed
153
Each section has the form:
Egbert Eich's avatar
Egbert Eich committed
154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170
.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"
171
.BR "Extensions     " "Extension enabling"
Egbert Eich's avatar
Egbert Eich committed
172
.BR "InputDevice    " "Input device description"
173
.BR "InputClass     " "Input class description"
Egbert Eich's avatar
Egbert Eich committed
174 175 176 177 178 179
.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"
Branden Robinson's avatar
Branden Robinson committed
180 181
.BR "DRI            " "DRI\-specific configuration"
.BR "Vendor         " "Vendor\-specific configuration"
Egbert Eich's avatar
Egbert Eich committed
182 183 184 185
.fi
.RE
.PP
The following obsolete section names are still recognised for compatibility
Branden Robinson's avatar
Branden Robinson committed
186 187
purposes.
In new config files, the
Egbert Eich's avatar
Egbert Eich committed
188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
.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
204 205
sections are at the highest level.
They bind together the input and output devices that will be used in a session.
Branden Robinson's avatar
Branden Robinson committed
206
The input devices are described in the
Egbert Eich's avatar
Egbert Eich committed
207
.B InputDevice
208
sections.
Branden Robinson's avatar
Branden Robinson committed
209
Output devices usually consist of multiple independent components (e.g.,
210
a graphics board and a monitor).
Branden Robinson's avatar
Branden Robinson committed
211
These multiple components are bound together in the
Egbert Eich's avatar
Egbert Eich committed
212 213 214
.B Screen
sections, and it is these that are referenced by the
.B ServerLayout
215
section.
Branden Robinson's avatar
Branden Robinson committed
216
Each
Egbert Eich's avatar
Egbert Eich committed
217
.B Screen
218
section binds together a graphics board and a monitor.
Branden Robinson's avatar
Branden Robinson committed
219
The graphics boards are described in the
Egbert Eich's avatar
Egbert Eich committed
220 221 222 223 224
.B Device
sections, and the monitors are described in the
.B Monitor
sections.
.PP
Branden Robinson's avatar
Branden Robinson committed
225
Config file keywords are case\-insensitive, and \(lq_\(rq characters are
226
ignored.
Branden Robinson's avatar
Branden Robinson committed
227
Most strings (including
Egbert Eich's avatar
Egbert Eich committed
228 229
.B Option
names) are also case-insensitive, and insensitive to white space and
Branden Robinson's avatar
Branden Robinson committed
230
\(lq_\(rq characters.
Egbert Eich's avatar
Egbert Eich committed
231
.PP
232 233 234
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.
Branden Robinson's avatar
Branden Robinson committed
235
The argument types are:
Egbert Eich's avatar
Egbert Eich committed
236 237 238 239 240 241 242 243 244
.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
Branden Robinson's avatar
Branden Robinson committed
245 246
Note: hex integer values must be prefixed with \(lq0x\(rq, and octal values
with \(lq0\(rq.
Egbert Eich's avatar
Egbert Eich committed
247 248 249
.PP
A special keyword called
.B Option
Branden Robinson's avatar
Branden Robinson committed
250
may be used to provide free\-form data to various components of the server.
Egbert Eich's avatar
Egbert Eich committed
251 252
The
.B Option
Branden Robinson's avatar
Branden Robinson committed
253 254 255 256
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:
Egbert Eich's avatar
Egbert Eich committed
257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272
.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
Branden Robinson's avatar
Branden Robinson committed
273 274
Boolean options may optionally have a value specified.
When no value is specified, the option's value is
Egbert Eich's avatar
Egbert Eich committed
275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326
.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.
Branden Robinson's avatar
Branden Robinson committed
327
.SH "FILES SECTION"
Egbert Eich's avatar
Egbert Eich committed
328 329 330
The
.B Files
section is used to specify some path names required by the server.
Branden Robinson's avatar
Branden Robinson committed
331 332 333 334 335 336 337
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
Egbert Eich's avatar
Egbert Eich committed
338 339 340 341 342 343
.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
Branden Robinson's avatar
Branden Robinson committed
344 345 346
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.
Egbert Eich's avatar
Egbert Eich committed
347 348 349
Multiple
.B FontPath
entries may be specified, and they will be concatenated to build up the
350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370
fontpath used by the server.  Font path elements can be absolute
directory paths, catalogue directories or a font server identifier. The
formats of the later two are explained below:
.PP
.RS 7
Catalogue directories:
.PP
.RS 4
Catalogue directories can be specified using the prefix \fBcatalogue:\fR
before the directory name. The directory can then be populated with
symlinks pointing to the real font directories, using the following
syntax in the symlink name:
.PP
.RS 4
.IR <identifier> : [attribute]: pri= <priority>
.RE
.PP
where
.I <identifier>
is an alphanumeric identifier,
.I [attribute]
371
is an attribute which will be passed to the underlying FPE and
372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387
.I <priority>
is a number used to order the fontfile FPEs. Examples:
.PP
.RS 4
.nf
.I 75dpi:unscaled:pri=20  -> /usr/share/X11/fonts/75dpi
.I gscript:pri=60 -> /usr/share/fonts/default/ghostscript
.I misc:unscaled:pri=10 \-> /usr/share/X11/fonts/misc
.fi
.PP
.RE .RE .RE
.PP
.RS 7
Font server identifiers:
.PP
.RS 4
Branden Robinson's avatar
Branden Robinson committed
388
Font server identifiers have the form:
389
.RS 4
Egbert Eich's avatar
Egbert Eich committed
390
.PP
Branden Robinson's avatar
Branden Robinson committed
391
.IR <trans> / <hostname> : <port\-number>
Egbert Eich's avatar
Egbert Eich committed
392 393 394 395 396 397
.RE
.PP
where
.I <trans>
is the transport type to use to connect to the font server (e.g.,
.B unix
Branden Robinson's avatar
Branden Robinson committed
398
for UNIX\-domain sockets or
Egbert Eich's avatar
Egbert Eich committed
399 400 401 402
.B tcp
for a TCP/IP connection),
.I <hostname>
is the hostname of the machine running the font server, and
Branden Robinson's avatar
Branden Robinson committed
403
.I <port\-number>
Egbert Eich's avatar
Egbert Eich committed
404
is the port number that the font server is listening on (usually 7100).
405
.RE
Egbert Eich's avatar
Egbert Eich committed
406 407
.PP
When this entry is not specified in the config file, the server falls back
Branden Robinson's avatar
Branden Robinson committed
408
to the compiled\-in default font path, which contains the following
409
font path elements (which can be set inside a catalogue directory):
Egbert Eich's avatar
Egbert Eich committed
410 411 412
.PP
.RS 4
.nf
413 414 415 416 417 418
.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/
Egbert Eich's avatar
Egbert Eich committed
419 420 421 422 423 424 425 426
.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
Branden Robinson's avatar
Branden Robinson committed
427 428 429 430
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
Egbert Eich's avatar
Egbert Eich committed
431 432
.B ModulePath
entries may be specified, and they will be concatenated to build the
433 434 435 436 437
module search path used by the server.  The default module path is
.PP
.RS 11
__modulepath__
.RE
Egbert Eich's avatar
Egbert Eich committed
438 439 440 441
.\" The LogFile keyword is not currently implemented
.ig
.TP 7
.BI "LogFile \*q" path \*q
Branden Robinson's avatar
Branden Robinson committed
442 443
sets the name of the __xservername__ server log file.
The default log file name is
Egbert Eich's avatar
Egbert Eich committed
444 445 446 447 448 449 450 451 452 453
.PP
.RS 11
.RI __logdir__/__xservername__. <n> .log
.RE
.PP
.RS 7
where
.I <n>
is the display number for the __xservername__ server.
..
454 455 456 457 458 459 460 461 462
.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
Branden Robinson's avatar
Branden Robinson committed
463
.SH "SERVERFLAGS SECTION"
464
In addition to options specific to this section (described below), the
Egbert Eich's avatar
Egbert Eich committed
465 466
.B ServerFlags
section is used to specify some global
467
__xservername__ server options.
Branden Robinson's avatar
Branden Robinson committed
468
All of the entries in this section are
Egbert Eich's avatar
Egbert Eich committed
469 470
.BR Options ,
although for compatibility purposes some of the old style entries are
471 472 473
still recognised.
Those old style entries are not documented here, and using them is
discouraged.
Branden Robinson's avatar
Branden Robinson committed
474
The
Egbert Eich's avatar
Egbert Eich committed
475 476 477 478 479 480 481 482 483 484 485
.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
Branden Robinson's avatar
Branden Robinson committed
486 487 488 489
section.
Options with command line equivalents are overridden when their command
line equivalent is used.
The options recognised by this section are:
Egbert Eich's avatar
Egbert Eich committed
490
.TP 7
Branden Robinson's avatar
Branden Robinson committed
491
.BI "Option \*qDefaultServerLayout\*q  \*q" layout\-id \*q
Egbert Eich's avatar
Egbert Eich committed
492 493 494 495 496 497 498
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
Branden Robinson's avatar
Branden Robinson committed
499 500 501 502 503 504 505
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.
Egbert Eich's avatar
Egbert Eich committed
506
.TP 7
507 508 509 510 511 512 513 514 515
.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
Egbert Eich's avatar
Egbert Eich committed
516 517 518 519 520
.BI "Option \*qDontVTSwitch\*q  \*q" boolean \*q
This disallows the use of the
.BI Ctrl+Alt+F n
sequence (where
.RI F n
Branden Robinson's avatar
Branden Robinson committed
521 522 523 524 525 526
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.
Egbert Eich's avatar
Egbert Eich committed
527 528 529
.TP 7
.BI "Option \*qDontZap\*q  \*q" boolean \*q
This disallows the use of the
530 531 532 533 534
.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.
Egbert Eich's avatar
Egbert Eich committed
535 536 537
.TP 7
.BI "Option \*qDontZoom\*q  \*q" boolean \*q
This disallows the use of the
Branden Robinson's avatar
Branden Robinson committed
538
.B Ctrl+Alt+Keypad\-Plus
Egbert Eich's avatar
Egbert Eich committed
539
and
Branden Robinson's avatar
Branden Robinson committed
540 541 542
.B Ctrl+Alt+Keypad\-Minus
sequences.
These sequences allows you to switch between video modes.
Egbert Eich's avatar
Egbert Eich committed
543
When this option is enabled, those key sequences have no special meaning
Branden Robinson's avatar
Branden Robinson committed
544 545
and are passed to clients.
Default: off.
Egbert Eich's avatar
Egbert Eich committed
546 547 548
.TP 7
.BI "Option \*qDisableVidModeExtension\*q  \*q" boolean \*q
This disables the parts of the VidMode extension used by the xvidtune client
Branden Robinson's avatar
Branden Robinson committed
549 550
that can be used to change the video modes.
Default: the VidMode extension is enabled.
Egbert Eich's avatar
Egbert Eich committed
551 552 553
.TP 7
.BI "Option \*qAllowNonLocalXvidtune\*q  \*q" boolean \*q
This allows the xvidtune client (and other clients that use the VidMode
Branden Robinson's avatar
Branden Robinson committed
554 555
extension) to connect from another host.
Default: off.
Egbert Eich's avatar
Egbert Eich committed
556 557
.TP 7
.BI "Option \*qAllowMouseOpenFail\*q  \*q" boolean \*q
558 559 560
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.
Branden Robinson's avatar
Branden Robinson committed
561
Default: false.
Egbert Eich's avatar
Egbert Eich committed
562 563
.TP 7
.BI "Option \*qBlankTime\*q  \*q" time \*q
Branden Robinson's avatar
Branden Robinson committed
564 565 566
sets the inactivity timeout for the
.B blank
phase of the screensaver.
Egbert Eich's avatar
Egbert Eich committed
567
.I time
Branden Robinson's avatar
Branden Robinson committed
568 569 570 571 572 573
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.
Egbert Eich's avatar
Egbert Eich committed
574 575
.TP 7
.BI "Option \*qStandbyTime\*q  \*q" time \*q
Branden Robinson's avatar
Branden Robinson committed
576 577 578
sets the inactivity timeout for the
.B standby
phase of DPMS mode.
Egbert Eich's avatar
Egbert Eich committed
579
.I time
Branden Robinson's avatar
Branden Robinson committed
580 581
is in minutes, and the value can be changed at run\-time with
.BR xset(__appmansuffix__).
582
Default: 10 minutes.
Branden Robinson's avatar
Branden Robinson committed
583 584 585
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
Egbert Eich's avatar
Egbert Eich committed
586 587 588 589
.B \*qDPMS\*q
option set (see the MONITOR section below).
.TP 7
.BI "Option \*qSuspendTime\*q  \*q" time \*q
Branden Robinson's avatar
Branden Robinson committed
590 591 592
sets the inactivity timeout for the
.B suspend
phase of DPMS mode.
Egbert Eich's avatar
Egbert Eich committed
593
.I time
Branden Robinson's avatar
Branden Robinson committed
594 595
is in minutes, and the value can be changed at run\-time with
.BR xset(__appmansuffix__).
596
Default: 10 minutes.
Branden Robinson's avatar
Branden Robinson committed
597 598 599
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
Egbert Eich's avatar
Egbert Eich committed
600 601 602 603
.B \*qDPMS\*q
option set (see the MONITOR section below).
.TP 7
.BI "Option \*qOffTime\*q  \*q" time \*q
Branden Robinson's avatar
Branden Robinson committed
604 605 606
sets the inactivity timeout for the
.B off
phase of DPMS mode.
Egbert Eich's avatar
Egbert Eich committed
607
.I time
Branden Robinson's avatar
Branden Robinson committed
608 609
is in minutes, and the value can be changed at run\-time with
.BR xset(__appmansuffix__).
610
Default: 10 minutes.
Branden Robinson's avatar
Branden Robinson committed
611 612 613
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
Egbert Eich's avatar
Egbert Eich committed
614 615 616 617
.B \*qDPMS\*q
option set (see the MONITOR section below).
.TP 7
.BI "Option \*qPixmap\*q  \*q" bpp \*q
Branden Robinson's avatar
Branden Robinson committed
618 619
This sets the pixmap format to use for depth 24.
Allowed values for
Egbert Eich's avatar
Egbert Eich committed
620
.I bpp
Branden Robinson's avatar
Branden Robinson committed
621 622 623
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.
Egbert Eich's avatar
Egbert Eich committed
624 625
.TP 7
.BI "Option \*qNoPM\*q  \*q" boolean \*q
Branden Robinson's avatar
Branden Robinson committed
626 627
Disables something to do with power management events.
Default: PM enabled on platforms that support it.
Egbert Eich's avatar
Egbert Eich committed
628 629
.TP 7
.BI "Option \*qXinerama\*q  \*q" boolean \*q
Branden Robinson's avatar
Branden Robinson committed
630 631
enable or disable XINERAMA extension.
Default is disabled.
Egbert Eich's avatar
Egbert Eich committed
632
.TP 7
633 634
.BI "Option \*qAIGLX\*q \*q" boolean \*q
enable or disable AIGLX. AIGLX is enabled by default.
635
.TP 7
636 637 638
.BI "Option \*qDRI2\*q \*q" boolean \*q
enable or disable DRI2. DRI2 is disabled by default.
.TP 7
639 640 641 642 643 644 645 646 647 648 649
.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
650 651 652 653 654
.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
655 656 657
.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.
658 659 660 661 662 663 664 665 666 667
.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.
668 669 670 671 672 673 674 675 676
.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.
Branden Robinson's avatar
Branden Robinson committed
677
.SH "MODULE SECTION"
Egbert Eich's avatar
Egbert Eich committed
678 679 680 681
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.
682 683
The type of modules normally loaded in this section are __xservername__ server
extension modules.
Branden Robinson's avatar
Branden Robinson committed
684 685
Most other module types are loaded automatically when they are needed via
other mechanisms.
Egbert Eich's avatar
Egbert Eich committed
686 687 688 689 690
The
.B Module
section is optional, as are all of the entries that may be specified in
it.
.PP
Branden Robinson's avatar
Branden Robinson committed
691 692
Entries in this section may be in two forms.
The first and most commonly used form is an entry that uses the
Egbert Eich's avatar
Egbert Eich committed
693 694 695 696 697 698 699
.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
Branden Robinson's avatar
Branden Robinson committed
700 701 702
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.
Egbert Eich's avatar
Egbert Eich committed
703 704
.PP
.RS 7
705
Example: the DRI extension module can be loaded with the following entry:
Egbert Eich's avatar
Egbert Eich committed
706 707
.PP
.RS 4
708
.B "Load \*qdri\*q"
Egbert Eich's avatar
Egbert Eich committed
709 710
.RE
.RE
711 712 713 714 715 716 717
.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
718
instruction is given for the same module, it overrides the
719 720 721 722 723 724
.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.
Egbert Eich's avatar
Egbert Eich committed
725 726 727 728 729 730 731 732 733 734
.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
Branden Robinson's avatar
Branden Robinson committed
735
server extensions) can be loaded, with the XFree86\-DGA extension
Egbert Eich's avatar
Egbert Eich committed
736 737 738 739 740
disabled by using the following entry:
.PP
.RS 4
.nf
.B "SubSection \*qextmod\*q"
Branden Robinson's avatar
Branden Robinson committed
741
.B "   Option  \*qomit XFree86\-DGA\*q"
Egbert Eich's avatar
Egbert Eich committed
742 743 744 745 746 747
.B EndSubSection
.fi
.RE
.PP
Modules are searched for in each directory specified in the
.B ModulePath
748 749
search path, and in the drivers, extensions, input, internal, and
multimedia subdirectories of each of those directories.
Egbert Eich's avatar
Egbert Eich committed
750 751 752
In addition to this, operating system specific subdirectories of all
the above are searched first if they exist.
.PP
753 754
To see what extension modules are available, check the extensions
subdirectory under:
Egbert Eich's avatar
Egbert Eich committed
755 756 757
.PP
.RS 4
.nf
758
__modulepath__
Egbert Eich's avatar
Egbert Eich committed
759 760 761
.fi
.RE
.PP
762 763 764
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.
Branden Robinson's avatar
Branden Robinson committed
765 766 767 768
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.
769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794
.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
Branden Robinson's avatar
Branden Robinson committed
795
.SH "INPUTDEVICE SECTION"
Egbert Eich's avatar
Egbert Eich committed
796 797
The config file may have multiple
.B InputDevice
Branden Robinson's avatar
Branden Robinson committed
798
sections.
799 800
Recent X servers employ HAL or udev backends for input device enumeration
and input hotplugging. It is usually not
801 802
necessary to provide
.B InputDevice
803 804 805 806 807 808 809 810
sections in the xorg.conf if hotplugging is in use. If hotplugging is
enabled,
.B InputDevice
sections using the
.B mouse, kbd
and
.B vmmouse
driver will be ignored.
811 812 813 814
.PP
If hotplugging is disabled, there will normally
be at least two: one for the core (primary) keyboard
and one for the core pointer.
Branden Robinson's avatar
Branden Robinson committed
815
If either of these two is missing, a default configuration for the missing
816 817 818 819 820 821 822 823 824 825 826 827
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.
Branden Robinson's avatar
Branden Robinson committed
828
Currently the default configuration may not work as expected on all platforms.
Egbert Eich's avatar
Egbert Eich committed
829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849
.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
Branden Robinson's avatar
Branden Robinson committed
850 851
sections.
All other entries are optional.
Egbert Eich's avatar
Egbert Eich committed
852 853 854
.PP
The
.B Identifier
Branden Robinson's avatar
Branden Robinson committed
855 856
entry specifies the unique name for this input device.
The
Egbert Eich's avatar
Egbert Eich committed
857 858 859 860 861 862
.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
Branden Robinson's avatar
Branden Robinson committed
863 864
section.
An
Egbert Eich's avatar
Egbert Eich committed
865 866 867 868 869 870 871 872 873
.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.
Branden Robinson's avatar
Branden Robinson committed
874
The most commonly used input drivers are
875 876 877
.BR evdev (__drivermansuffix__)
on Linux systems, and
.BR kbd (__drivermansuffix__)
Branden Robinson's avatar
Branden Robinson committed
878
and
879
.BR mousedrv (__drivermansuffix__)
880
on other platforms.
Egbert Eich's avatar
Egbert Eich committed
881 882 883
.PP
.PP
.B InputDevice
Branden Robinson's avatar
Branden Robinson committed
884
sections recognise some driver\-independent
Egbert Eich's avatar
Egbert Eich committed
885
.BR Options ,
Branden Robinson's avatar
Branden Robinson committed
886 887 888
which are described here.
See the individual input driver manual pages for a description of the
device\-specific options.
Egbert Eich's avatar
Egbert Eich committed
889
.TP 7
890 891 892 893 894
.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
Egbert Eich's avatar
Egbert Eich committed
895
.BI "Option \*qCorePointer\*q"
896 897
Deprecated, see
.B Floating
Egbert Eich's avatar
Egbert Eich committed
898 899
.TP 7
.BI "Option \*qCoreKeyboard\*q"
900 901
Deprecated, see
.B Floating
Egbert Eich's avatar
Egbert Eich committed
902 903
.TP 7
.BI "Option \*qAlwaysCore\*q  \*q" boolean \*q
904 905
Deprecated, see
.B Floating
Egbert Eich's avatar
Egbert Eich committed
906 907
.TP 7
.BI "Option \*qSendCoreEvents\*q  \*q" boolean \*q
908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931
Deprecated, see
.B Floating

.TP 7
.BI "Option \*qFloating\*q  \*q" boolean \*q
When enabled, the input device is set up floating and does not
report events through any master device or control a cursor. The device is
only available to clients using the X Input Extension API. This option is
disabled by default.
The options
.B CorePointer,
.B CoreKeyboard,
.B AlwaysCore,
and
.B SendCoreEvents,
are the inverse of option
.B Floating
(i.e.
.B SendCoreEvents \*qon\*q
is equivalent to
.B Floating \*qoff\*q
).

This option controls the startup behavior only, a device
932
may be reattached or set floating at runtime.
933 934 935 936 937 938 939 940 941 942 943
.TP 7
.BI "Option \*qTransformationMatrix\*q \*q" a " " b " " c " " d " " e " " f " " g " " h " " i \*q
Specifies the 3x3 transformation matrix for absolute input devices. The
input device will be bound to the area given in the matrix.  In most
configurations, "a" and "e" specify the width and height of the area the
device is bound to, and "c" and "f" specify the x and y offset of the area.
The value range is 0 to 1, where 1 represents the width or height of all
root windows together, 0.5 represents half the area, etc. The values
represent a 3x3 matrix, with the first, second and third group of three
values representing the first, second and third row of the matrix,
respectively.  The identity matrix is "1 0 0 0 1 0 0 0 1".
944
.SS POINTER ACCELERATION
945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987
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"
988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007
.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.
1008

1009 1010 1011 1012 1013 1014 1015 1016
.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
1017 1018
section. Each class can override settings from a previous class, so it is
best to arrange the sections with the most generic matches first.
1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049
.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
1050
module from the first
1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062
.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.
.PP
1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082
There are two types of match entries used in
.B InputClass
sections. The first allows various tokens to be matched against attributes
of the device. An entry can be constructed to match attributes from different
devices by separating arguments with a '|' character. Multiple entries of the
same type may be supplied to add multiple matching conditions on the same
attribute. For example:
.PP
.RS 4
.nf
.B  "Section \*qInputClass\*q"
.B  "    Identifier   \*qMy Class\*q"
.B  "    # product string must contain example and
.B  "    # either gizmo or gadget
.B  "    MatchProduct \*qexample\*q
.B  "    MatchProduct \*qgizmo|gadget\*q
.I  "    ..."
.B  "EndSection"
.fi
.RE
1083 1084 1085 1086
.TP 7
.BI "MatchProduct  \*q" matchproduct \*q
This entry can be used to check if the substring
.RI \*q matchproduct \*q
1087
occurs in the device's product name.
1088 1089 1090 1091
.TP 7
.BI "MatchVendor  \*q" matchvendor \*q
This entry can be used to check if the substring
.RI \*q matchvendor \*q
1092
occurs in the device's vendor name.
1093 1094 1095 1096
.TP 7
.BI "MatchDevicePath \*q" matchdevice \*q
This entry can be used to check if the device file matches the
.RI \*q matchdevice \*q
1097
pathname pattern.
1098
.TP 7
1099 1100 1101 1102 1103 1104
.BI "MatchOS \*q" matchos \*q
This entry can be used to check if the operating system matches the
case-insensitive
.RI \*q matchos \*q
string. This entry is only supported on platforms providing the
.BR uname (2)
1105
system call.
1106
.TP 7
1107 1108 1109
.BI "MatchPnPID \*q" matchpnp \*q
The device's Plug and Play (PnP) ID can be checked against the
.RI \*q matchpnp \*q
1110
shell wildcard pattern.
1111
.TP 7
1112 1113 1114 1115 1116 1117
.BI "MatchUSBID \*q" matchusb \*q
The device's USB ID can be checked against the
.RI \*q matchusb \*q
shell wildcard pattern. The ID is constructed as lowercase hexadecimal numbers
separated by a ':'. This is the same format as the
.BR lsusb (8)
1118
program.
1119
.TP 7
1120 1121 1122 1123 1124 1125 1126 1127 1128
.BI "MatchDriver \*q" matchdriver \*q
Check the case-sensitive string
.RI \*q matchdriver \*q
against the currently configured driver of the device. Ordering of sections
using this entry is important since it will not match unless the driver has
been set by the config backend or a previous
.B InputClass
section.
.TP 7
1129 1130 1131 1132
.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
1133
pattern. A match is found if at least one of the tags given in
1134 1135
.RI \*q matchtag \*q
matches at least one of the tags assigned by the backend.
1136 1137 1138 1139 1140 1141 1142 1143 1144 1145
.TP 7
.BI "MatchLayout \*q" matchlayout \*q
Check the case-sensitive string
.RI \*q matchlayout \*q
against the currently active
.B ServerLayout
section. The empty string "" matches an implicit layout which appears
if no named
.B ServerLayout
sections have been found.
1146 1147 1148 1149 1150
.PP
The second type of entry is used to match device types. These entries take a
boolean argument similar to
.B Option
entries.
1151
.TP 7
1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167
.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
.PP
When an input device has been matched to the
.B InputClass
section, any
.B Option
1168 1169 1170 1171 1172
entries are applied to the device. One
.B InputClass
specific
.B Option
is recognized. See the
1173
.B InputDevice
1174
section above for a description of the remaining
1175 1176
.B Option
entries.
1177 1178 1179 1180 1181
.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.
Branden Robinson's avatar
Branden Robinson committed
1182
.SH "DEVICE SECTION"
Egbert Eich's avatar
Egbert Eich committed
1183 1184
The config file may have multiple
.B Device
Branden Robinson's avatar
Branden Robinson committed
1185 1186
sections.
There must be at least one, for the video card being used.
Egbert Eich's avatar
Egbert Eich committed
1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211
.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
Branden Robinson's avatar
Branden Robinson committed
1212 1213
entry specifies the unique name for this graphics device.
The
Egbert Eich's avatar
Egbert Eich committed
1214 1215 1216 1217 1218 1219
.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
Branden Robinson's avatar
Branden Robinson committed
1220 1221
section.
A
Egbert Eich's avatar
Egbert Eich committed
1222 1223 1224 1225 1226 1227
.B Device
section is considered active if it is referenced by an active
.B Screen
section.
.PP
.B Device
Branden Robinson's avatar
Branden Robinson committed
1228
sections recognise some driver\-independent entries and
Egbert Eich's avatar
Egbert Eich committed
1229
.BR Options ,
Branden Robinson's avatar
Branden Robinson committed
1230 1231 1232 1233 1234 1235
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.
Egbert Eich's avatar
Egbert Eich committed
1236 1237 1238 1239 1240 1241 1242 1243
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
Branden Robinson's avatar
Branden Robinson committed
1244 1245 1246
.BI "BusID  \*q" bus\-id \*q
This specifies the bus location of the graphics card.
For PCI/AGP cards,
Egbert Eich's avatar
Egbert Eich committed
1247
the
Branden Robinson's avatar
Branden Robinson committed
1248
.I bus\-id
Egbert Eich's avatar
Egbert Eich committed
1249 1250
string has the form
.BI PCI: bus : device : function
Branden Robinson's avatar
Branden Robinson committed
1251
(e.g., \(lqPCI:1:0:0\(rq might be appropriate for an AGP card).
Egbert Eich's avatar
Egbert Eich committed
1252
This field is usually optional in single-head configurations when using
Branden Robinson's avatar
Branden Robinson committed
1253 1254 1255 1256 1257
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.
1258 1259
This information can usually be found by running the pciaccess tool
scanpci.
Egbert Eich's avatar
Egbert Eich committed
1260 1261 1262 1263
.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
Branden Robinson's avatar
Branden Robinson committed
1264 1265
and video memory).
One
Egbert Eich's avatar
Egbert Eich committed
1266 1267 1268 1269
.B Device
section is required for each head, and this
parameter determines which head each of the
.B Device
Branden Robinson's avatar
Branden Robinson committed
1270 1271
sections applies to.
The legal values of
Egbert Eich's avatar
Egbert Eich committed
1272 1273 1274 1275 1276 1277
.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
Branden Robinson's avatar
Branden Robinson committed
1278 1279 1280 1281
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
Egbert Eich's avatar
Egbert Eich committed
1282 1283
do.
.TP 7
Branden Robinson's avatar
Branden Robinson committed
1284
.BI "Ramdac  \*q" ramdac\-type \*q
Egbert Eich's avatar
Egbert Eich committed
1285
This optional entry specifies the type of RAMDAC used on the graphics
Branden Robinson's avatar
Branden Robinson committed
1286 1287 1288 1289 1290 1291
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.
Egbert Eich's avatar
Egbert Eich committed
1292 1293 1294
.TP 7
.BI "DacSpeed  " speed
.TP 7
Branden Robinson's avatar
Branden Robinson committed
1295
.BI "DacSpeed  " "speed\-8 speed\-16 speed\-24 speed\-32"
Egbert Eich's avatar
Egbert Eich committed
1296
This optional entry specifies the RAMDAC speed rating (which is usually
Branden Robinson's avatar
Branden Robinson committed
1297 1298 1299 1300 1301 1302 1303 1304 1305 1306
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.
Egbert Eich's avatar
Egbert Eich committed
1307 1308
.TP 7
.BI "Clocks  " "clock ..."
Branden Robinson's avatar
Branden Robinson committed
1309 1310 1311 1312 1313 1314
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
Egbert Eich's avatar
Egbert Eich committed
1315
.B Clocks
Branden Robinson's avatar
Branden Robinson committed
1316 1317 1318 1319 1320
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.
Egbert Eich's avatar
Egbert Eich committed
1321
.TP
Branden Robinson's avatar
Branden Robinson committed
1322
.BI "ClockChip  \*q" clockchip\-type \*q
Egbert Eich's avatar
Egbert Eich committed
1323
This optional entry is used to specify the clock chip type on graphics
Branden Robinson's avatar
Branden Robinson committed
1324 1325 1326
boards which have a programmable clock generator.
Only a few __xservername__ drivers support programmable clock chips.
For details, see the appropriate driver manual page.
Egbert Eich's avatar
Egbert Eich committed
1327 1328 1329
.TP 7
.BI "VideoRam  " "mem"
This optional entry specifies the amount of video ram that is installed
Branden Robinson's avatar
Branden Robinson committed
1330 1331 1332 1333 1334
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.
Egbert Eich's avatar
Egbert Eich committed
1335 1336 1337
.TP 7
.BI "BiosBase  " "baseaddress"
This optional entry specifies the base address of the video BIOS for
Branden Robinson's avatar
Branden Robinson committed
1338 1339 1340
the VGA board.
This address is normally auto-detected, and should only be specified if the
driver-specific documentation recommends it.
Egbert Eich's avatar
Egbert Eich committed
1341 1342 1343
.TP 7
.BI "MemBase  " "baseaddress"
This optional entry specifies the memory base address of a graphics
Branden Robinson's avatar
Branden Robinson committed
1344 1345 1346
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.
Egbert Eich's avatar
Egbert Eich committed
1347 1348
.TP 7
.BI "IOBase  " "baseaddress"
Branden Robinson's avatar
Branden Robinson committed
1349 1350 1351
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.
Egbert Eich's avatar
Egbert Eich committed
1352 1353 1354
.TP 7
.BI "ChipID  " "id"
This optional entry specifies a numerical ID representing the chip type.
Branden Robinson's avatar
Branden Robinson committed
1355 1356 1357
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.
Egbert Eich's avatar
Egbert Eich committed
1358 1359
.TP 7
.BI "ChipRev  " "rev"
Branden Robinson's avatar
Branden Robinson committed
1360 1361 1362
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.
Egbert Eich's avatar
Egbert Eich committed
1363 1364 1365
.TP 7
.BI "TextClockFreq  " "freq"
This optional entry specifies the pixel clock frequency that is used
Branden Robinson's avatar
Branden Robinson committed
1366 1367 1368
for the regular text mode.
The frequency is specified in MHz.
This is rarely used.
1369 1370 1371 1372
.TP 7
.BI "Option \*qModeDebug\*q \*q" boolean \*q
Enable printing of additional debugging information about modesetting to
the server log.
Egbert Eich's avatar
Egbert Eich committed
1373 1374 1375 1376 1377 1378 1379 1380
.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
Branden Robinson's avatar
Branden Robinson committed
1381 1382 1383
sections.
These include driver\-specific options and driver\-independent options.
The former are described in the driver\-specific documentation.
Egbert Eich's avatar
Egbert Eich committed
1384 1385 1386 1387
Some of the latter are described below in the section about the
.B Screen
section, and they may also be included here.

Branden Robinson's avatar
Branden Robinson committed
1388 1389 1390
.SH "VIDEOADAPTOR SECTION"
Nobody wants to say how this works.