xorg.conf.man.pre 66 KB
Newer Older
1
.\" $XdotOrg: xserver/xorg/hw/xfree86/doc/man/xorg.conf.man.pre,v 1.7 2006/05/26 00:12:18 reed Exp $
Egbert Eich's avatar
Egbert Eich committed
2
3
4
5
.\" shorthand for double quote that works everywhere.
.ds q \N'34'
.TH __xconfigfile__ __filemansuffix__ __vendorversion__
.SH NAME
Branden Robinson's avatar
Branden Robinson committed
6
__xconfigfile__ \- configuration File for __xservername__ X server
Egbert Eich's avatar
Egbert Eich committed
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
.SH INTRODUCTION
.B __xservername__
supports several mechanisms for supplying/obtaining configuration and
run-time parameters: command line options, environment variables, the
__xconfigfile__ configuration file, auto-detection, and fallback defaults.
When the same information is supplied in more than one way, the highest
precedence mechanism is used.  The list of mechanisms is ordered from
highest precedence to lowest.  Note that not all parameters can be
supplied via all methods.  The available command line options and
environment variables (and some defaults) are described in the Xserver(__appmansuffix__)
and __xservername__(__appmansuffix__) manual pages.  Most configuration file parameters, with
their defaults, are described below.  Driver and module specific
configuration parameters are described in the relevant driver or module
manual page.
.SH DESCRIPTION
.B __xservername__
uses a configuration file called
Branden Robinson's avatar
Branden Robinson committed
24
25
26
27
.I __xconfigfile__
for its initial setup.
This configuration file is searched for in the following places when the
server is started as a normal user:
Egbert Eich's avatar
Egbert Eich committed
28
29
30
31
32
33
34
.PP
.RS 4
.nf
.IR /etc/X11/ <cmdline>
.IR __projectroot__/etc/X11/ <cmdline>
.IB /etc/X11/ $XORGCONFIG
.IB __projectroot__/etc/X11/ $XORGCONFIG
Branden Robinson's avatar
Branden Robinson committed
35
.I /etc/X11/__xconfigfile__\-4
Egbert Eich's avatar
Egbert Eich committed
36
37
38
.I /etc/X11/__xconfigfile__
.I /etc/__xconfigfile__
.IR __projectroot__/etc/X11/__xconfigfile__. <hostname>
Branden Robinson's avatar
Branden Robinson committed
39
.I __projectroot__/etc/X11/__xconfigfile__\-4
Egbert Eich's avatar
Egbert Eich committed
40
41
.I __projectroot__/etc/X11/__xconfigfile__
.IR __projectroot__/lib/X11/__xconfigfile__. <hostname>
Branden Robinson's avatar
Branden Robinson committed
42
.I __projectroot__/lib/X11/__xconfigfile__\-4
Egbert Eich's avatar
Egbert Eich committed
43
44
45
46
47
48
.I __projectroot__/lib/X11/__xconfigfile__
.fi
.RE
.PP
where
.I <cmdline>
Branden Robinson's avatar
Branden Robinson committed
49
is a relative path (with no \(lq..\(rq components) specified with the
Egbert Eich's avatar
Egbert Eich committed
50
51
52
.B \-config
command line option,
.B $XORGCONFIG
Branden Robinson's avatar
Branden Robinson committed
53
is the relative path (with no \(lq..\(rq components) specified by that
Egbert Eich's avatar
Egbert Eich committed
54
55
environment variable, and
.I <hostname>
Branden Robinson's avatar
Branden Robinson committed
56
57
is the machine's hostname as reported by
.BR gethostname (__oslibmansuffix__).
Egbert Eich's avatar
Egbert Eich committed
58
.PP
Branden Robinson's avatar
Branden Robinson committed
59
When the __xservername__ server is started by the \(lqroot\(rq user, the config file
Egbert Eich's avatar
Egbert Eich committed
60
61
62
63
64
65
66
67
68
69
70
search locations are as follows:
.PP
.RS 4
.nf
<cmdline>
.IR /etc/X11/ <cmdline>
.IR __projectroot__/etc/X11/ <cmdline>
.B $XORGCONFIG
.IB /etc/X11/ $XORGCONFIG
.IB __projectroot__/etc/X11/ $XORGCONFIG
.BI $HOME /__xconfigfile__
Branden Robinson's avatar
Branden Robinson committed
71
.I /etc/X11/__xconfigfile__\-4
Egbert Eich's avatar
Egbert Eich committed
72
73
74
.I /etc/X11/__xconfigfile__
.I /etc/__xconfigfile__
.IR __projectroot__/etc/X11/__xconfigfile__. <hostname>
Branden Robinson's avatar
Branden Robinson committed
75
.I __projectroot__/etc/X11/__xconfigfile__\-4
Egbert Eich's avatar
Egbert Eich committed
76
77
.I __projectroot__/etc/X11/__xconfigfile__
.IR __projectroot__/lib/X11/__xconfigfile__. <hostname>
Branden Robinson's avatar
Branden Robinson committed
78
.I __projectroot__/lib/X11/__xconfigfile__\-4
Egbert Eich's avatar
Egbert Eich committed
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
.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
96
is the machine's hostname as reported by
.BR gethostname (__oslibmansuffix__).
Egbert Eich's avatar
Egbert Eich committed
97
98
.PP
The
Branden Robinson's avatar
Branden Robinson committed
99
100
101
.I __xconfigfile__
file is composed of a number of sections which may be present in any order.
Each section has the form:
Egbert Eich's avatar
Egbert Eich committed
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
.PP
.RS 4
.nf
.BI "Section  \*q" SectionName \*q
.RI "    " SectionEntry
    ...
.B EndSection
.fi
.RE
.PP
The section names are:
.PP
.RS 4
.nf
.BR "Files          " "File pathnames"
.BR "ServerFlags    " "Server flags"
.BR "Module         " "Dynamic module loading"
.BR "InputDevice    " "Input device description"
.BR "Device         " "Graphics device description"
.BR "VideoAdaptor   " "Xv video adaptor description"
.BR "Monitor        " "Monitor description"
.BR "Modes          " "Video modes descriptions"
.BR "Screen         " "Screen configuration"
.BR "ServerLayout   " "Overall layout"
Branden Robinson's avatar
Branden Robinson committed
126
127
.BR "DRI            " "DRI\-specific configuration"
.BR "Vendor         " "Vendor\-specific configuration"
Egbert Eich's avatar
Egbert Eich committed
128
129
130
131
.fi
.RE
.PP
The following obsolete section names are still recognised for compatibility
Branden Robinson's avatar
Branden Robinson committed
132
133
purposes.
In new config files, the
Egbert Eich's avatar
Egbert Eich committed
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
.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
Branden Robinson's avatar
Branden Robinson committed
150
151
152
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
Egbert Eich's avatar
Egbert Eich committed
153
.B InputDevice
Branden Robinson's avatar
Branden Robinson committed
154
155
156
157
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
Egbert Eich's avatar
Egbert Eich committed
158
159
160
.B Screen
sections, and it is these that are referenced by the
.B ServerLayout
Branden Robinson's avatar
Branden Robinson committed
161
162
section.  
Each
Egbert Eich's avatar
Egbert Eich committed
163
.B Screen
Branden Robinson's avatar
Branden Robinson committed
164
165
section binds together a graphics board and a monitor.  
The graphics boards are described in the
Egbert Eich's avatar
Egbert Eich committed
166
167
168
169
170
.B Device
sections, and the monitors are described in the
.B Monitor
sections.
.PP
Branden Robinson's avatar
Branden Robinson committed
171
172
173
Config file keywords are case\-insensitive, and \(lq_\(rq characters are
ignored.  
Most strings (including
Egbert Eich's avatar
Egbert Eich committed
174
175
.B Option
names) are also case-insensitive, and insensitive to white space and
Branden Robinson's avatar
Branden Robinson committed
176
\(lq_\(rq characters.
Egbert Eich's avatar
Egbert Eich committed
177
.PP
Branden Robinson's avatar
Branden Robinson committed
178
179
180
181
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:
Egbert Eich's avatar
Egbert Eich committed
182
183
184
185
186
187
188
189
190
.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
191
192
Note: hex integer values must be prefixed with \(lq0x\(rq, and octal values
with \(lq0\(rq.
Egbert Eich's avatar
Egbert Eich committed
193
194
195
.PP
A special keyword called
.B Option
Branden Robinson's avatar
Branden Robinson committed
196
may be used to provide free\-form data to various components of the server.
Egbert Eich's avatar
Egbert Eich committed
197
198
The
.B Option
Branden Robinson's avatar
Branden Robinson committed
199
200
201
202
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
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
.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
219
220
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
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
.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
273
.SH "FILES SECTION"
Egbert Eich's avatar
Egbert Eich committed
274
275
276
The
.B Files
section is used to specify some path names required by the server.
Branden Robinson's avatar
Branden Robinson committed
277
278
279
280
281
282
283
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
284
285
286
287
288
289
.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
290
291
292
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
293
294
295
Multiple
.B FontPath
entries may be specified, and they will be concatenated to build up the
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
327
328
329
330
331
332
333
fontpath used by the server.  Font path elements can be absolute
directory paths, catalogue directories or a font server identifier. The
formats of the later two are explained below:
.PP
.RS 7
Catalogue directories:
.PP
.RS 4
Catalogue directories can be specified using the prefix \fBcatalogue:\fR
before the directory name. The directory can then be populated with
symlinks pointing to the real font directories, using the following
syntax in the symlink name:
.PP
.RS 4
.IR <identifier> : [attribute]: pri= <priority>
.RE
.PP
where
.I <identifier>
is an alphanumeric identifier,
.I [attribute]
is an attribute wich will be passed to the underlying FPE and
.I <priority>
is a number used to order the fontfile FPEs. Examples:
.PP
.RS 4
.nf
.I 75dpi:unscaled:pri=20  -> /usr/share/X11/fonts/75dpi
.I gscript:pri=60 -> /usr/share/fonts/default/ghostscript
.I misc:unscaled:pri=10 \-> /usr/share/X11/fonts/misc
.fi
.PP
.RE .RE .RE
.PP
.RS 7
Font server identifiers:
.PP
.RS 4
Branden Robinson's avatar
Branden Robinson committed
334
Font server identifiers have the form:
335
.RS 4
Egbert Eich's avatar
Egbert Eich committed
336
.PP
Branden Robinson's avatar
Branden Robinson committed
337
.IR <trans> / <hostname> : <port\-number>
Egbert Eich's avatar
Egbert Eich committed
338
339
340
341
342
343
.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
344
for UNIX\-domain sockets or
Egbert Eich's avatar
Egbert Eich committed
345
346
347
348
.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
349
.I <port\-number>
Egbert Eich's avatar
Egbert Eich committed
350
is the port number that the font server is listening on (usually 7100).
351
.RE
Egbert Eich's avatar
Egbert Eich committed
352
353
.PP
When this entry is not specified in the config file, the server falls back
Branden Robinson's avatar
Branden Robinson committed
354
to the compiled\-in default font path, which contains the following
355
font path elements (which can be set inside a catalogue directory):
Egbert Eich's avatar
Egbert Eich committed
356
357
358
359
.PP
.RS 4
.nf
.I __projectroot__/lib/X11/fonts/misc/
360
.I __projectroot__/lib/X11/fonts/TTF/
Egbert Eich's avatar
Egbert Eich committed
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
.I __projectroot__/lib/X11/fonts/Type1/
.I __projectroot__/lib/X11/fonts/75dpi/
.I __projectroot__/lib/X11/fonts/100dpi/
.fi
.RE
.PP
The recommended font path contains the following font path elements:
.PP
.RS 4
.nf
.I __projectroot__/lib/X11/fonts/local/
.I __projectroot__/lib/X11/fonts/misc/
.I __projectroot__/lib/X11/fonts/75dpi/:unscaled
.I __projectroot__/lib/X11/fonts/100dpi/:unscaled
.I __projectroot__/lib/X11/fonts/Type1/
.I __projectroot__/lib/X11/fonts/75dpi/
.I __projectroot__/lib/X11/fonts/100dpi/
.fi
.RE
.PP
Font path elements that are found to be invalid are removed from the
font path when the server starts up.
.RE
.TP 7
.BI "ModulePath \*q" path \*q
Branden Robinson's avatar
Branden Robinson committed
386
387
388
389
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
390
391
392
393
394
395
396
.B ModulePath
entries may be specified, and they will be concatenated to build the
module search path used by the server.
.\" The LogFile keyword is not currently implemented
.ig
.TP 7
.BI "LogFile \*q" path \*q
Branden Robinson's avatar
Branden Robinson committed
397
398
sets the name of the __xservername__ server log file.
The default log file name is
Egbert Eich's avatar
Egbert Eich committed
399
400
401
402
403
404
405
406
407
408
.PP
.RS 11
.RI __logdir__/__xservername__. <n> .log
.RE
.PP
.RS 7
where
.I <n>
is the display number for the __xservername__ server.
..
Branden Robinson's avatar
Branden Robinson committed
409
.SH "SERVERFLAGS SECTION"
410
In addition to options specific to this section (described below), the
Egbert Eich's avatar
Egbert Eich committed
411
412
.B ServerFlags
section is used to specify some global
Branden Robinson's avatar
Branden Robinson committed
413
414
__xservername__ server options.  
All of the entries in this section are
Egbert Eich's avatar
Egbert Eich committed
415
416
.BR Options ,
although for compatibility purposes some of the old style entries are
Branden Robinson's avatar
Branden Robinson committed
417
418
419
420
still recognised.  
Those old style entries are not documented here, and using them is 
discouraged.  
The
Egbert Eich's avatar
Egbert Eich committed
421
422
423
424
425
426
427
428
429
430
431
.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
432
433
434
435
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
436
.TP 7
Branden Robinson's avatar
Branden Robinson committed
437
.BI "Option \*qDefaultServerLayout\*q  \*q" layout\-id \*q
Egbert Eich's avatar
Egbert Eich committed
438
439
440
441
442
443
444
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
445
446
447
448
449
450
451
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
452
453
454
455
456
457
.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
Branden Robinson's avatar
Branden Robinson committed
458
459
460
461
462
463
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
464
465
466
467
.TP 7
.BI "Option \*qDontZap\*q  \*q" boolean \*q
This disallows the use of the
.B Ctrl+Alt+Backspace
Branden Robinson's avatar
Branden Robinson committed
468
469
470
471
472
sequence.
That sequence is normally used to terminate the __xservername__ server.
When this option is enabled, that key sequence has no special meaning and
is passed to clients.
Default: off.
Egbert Eich's avatar
Egbert Eich committed
473
474
475
.TP 7
.BI "Option \*qDontZoom\*q  \*q" boolean \*q
This disallows the use of the
Branden Robinson's avatar
Branden Robinson committed
476
.B Ctrl+Alt+Keypad\-Plus
Egbert Eich's avatar
Egbert Eich committed
477
and
Branden Robinson's avatar
Branden Robinson committed
478
479
480
.B Ctrl+Alt+Keypad\-Minus
sequences.
These sequences allows you to switch between video modes.
Egbert Eich's avatar
Egbert Eich committed
481
When this option is enabled, those key sequences have no special meaning
Branden Robinson's avatar
Branden Robinson committed
482
483
and are passed to clients.
Default: off.
Egbert Eich's avatar
Egbert Eich committed
484
485
486
.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
487
488
that can be used to change the video modes.
Default: the VidMode extension is enabled.
Egbert Eich's avatar
Egbert Eich committed
489
490
491
.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
492
493
extension) to connect from another host.
Default: off.
Egbert Eich's avatar
Egbert Eich committed
494
495
.TP 7
.BI "Option \*qDisableModInDev\*q  \*q" boolean \*q
Branden Robinson's avatar
Branden Robinson committed
496
497
498
This disables the parts of the __xservername__\-Misc extension that can be used to
modify the input device settings dynamically.
Default: that functionality is enabled.
Egbert Eich's avatar
Egbert Eich committed
499
500
501
.TP 7
.BI "Option \*qAllowNonLocalModInDev\*q  \*q" boolean \*q
This allows a client to connect from another host and change keyboard
Branden Robinson's avatar
Branden Robinson committed
502
503
and mouse settings in the running server.
Default: off.
Egbert Eich's avatar
Egbert Eich committed
504
505
506
.TP 7
.BI "Option \*qAllowMouseOpenFail\*q  \*q" boolean \*q
This allows the server to start up even if the mouse device can't be
Branden Robinson's avatar
Branden Robinson committed
507
508
opened/initialised.
Default: false.
Egbert Eich's avatar
Egbert Eich committed
509
510
511
512
513
.TP 7
.BI "Option \*qVTInit\*q  \*q" command \*q
Runs
.I command
after the VT used by the server has been opened.
Branden Robinson's avatar
Branden Robinson committed
514
515
516
517
518
519
The command string is passed to \*q/bin/sh \-c\*q, and is run with the real
user's id with stdin and stdout set to the VT.
The purpose of this option is to allow system dependent VT initialisation
commands to be run.
This option should rarely be needed.
Default: not set.
Egbert Eich's avatar
Egbert Eich committed
520
521
.TP 7
.BI "Option \*qVTSysReq\*q  \*q" boolean \*q
Branden Robinson's avatar
Branden Robinson committed
522
523
524
525
526
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
Egbert Eich's avatar
Egbert Eich committed
527
528
529
.RB ( Fn ).
This prevents the __xservername__ server trapping the
keys used for the default VT switch sequence, which means that clients can
Branden Robinson's avatar
Branden Robinson committed
530
531
access them.
Default: off.
Egbert Eich's avatar
Egbert Eich committed
532
533
.TP 7
.BI "Option \*qXkbDisable\*q \*q" boolean \*q
Branden Robinson's avatar
Branden Robinson committed
534
535
536
disable/enable the XKEYBOARD extension.
The \-kb command line option overrides this config file option.
Default: XKB is enabled.
Egbert Eich's avatar
Egbert Eich committed
537
538
539
540
.\" The following four options are "undocumented".
.ig
.TP 7
.BI "Option \*qPciProbe1\*q"
Branden Robinson's avatar
Branden Robinson committed
541
542
Use PCI probe method 1.
Default: set.
Egbert Eich's avatar
Egbert Eich committed
543
544
.TP 7
.BI "Option \*qPciProbe2\*q"
Branden Robinson's avatar
Branden Robinson committed
545
546
Use PCI probe method 2.
Default: not set.
Egbert Eich's avatar
Egbert Eich committed
547
548
.TP 7
.BI "Option \*qPciForceConfig1\*q"
Branden Robinson's avatar
Branden Robinson committed
549
550
Force the use PCI config type 1.
Default: not set.
Egbert Eich's avatar
Egbert Eich committed
551
552
.TP 7
.BI "Option \*qPciForceConfig2\*q"
Branden Robinson's avatar
Branden Robinson committed
553
554
Force the use PCI config type 2. 
Default: not set.
Egbert Eich's avatar
Egbert Eich committed
555
556
557
..
.TP 7
.BI "Option \*qBlankTime\*q  \*q" time \*q
Branden Robinson's avatar
Branden Robinson committed
558
559
560
sets the inactivity timeout for the
.B blank
phase of the screensaver.
Egbert Eich's avatar
Egbert Eich committed
561
.I time
Branden Robinson's avatar
Branden Robinson committed
562
563
564
565
566
567
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
568
569
.TP 7
.BI "Option \*qStandbyTime\*q  \*q" time \*q
Branden Robinson's avatar
Branden Robinson committed
570
571
572
sets the inactivity timeout for the
.B standby
phase of DPMS mode.
Egbert Eich's avatar
Egbert Eich committed
573
.I time
Branden Robinson's avatar
Branden Robinson committed
574
575
576
577
578
579
is in minutes, and the value can be changed at run\-time with
.BR xset(__appmansuffix__).
Default: 20 minutes.
This is only suitable for VESA DPMS compatible monitors, and may not be
supported by all video drivers.
It is only enabled for screens that have the
Egbert Eich's avatar
Egbert Eich committed
580
581
582
583
.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
584
585
586
sets the inactivity timeout for the
.B suspend
phase of DPMS mode.
Egbert Eich's avatar
Egbert Eich committed
587
.I time
Branden Robinson's avatar
Branden Robinson committed
588
589
590
591
592
593
is in minutes, and the value can be changed at run\-time with
.BR xset(__appmansuffix__).
Default: 30 minutes.
This is only suitable for VESA DPMS compatible monitors, and may not be
supported by all video drivers.
It is only enabled for screens that have the
Egbert Eich's avatar
Egbert Eich committed
594
595
596
597
.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
598
599
600
sets the inactivity timeout for the
.B off
phase of DPMS mode.
Egbert Eich's avatar
Egbert Eich committed
601
.I time
Branden Robinson's avatar
Branden Robinson committed
602
603
604
605
606
607
is in minutes, and the value can be changed at run\-time with
.BR xset(__appmansuffix__).
Default: 40 minutes. 
This is only suitable for VESA DPMS compatible monitors, and may not be
supported by all video drivers.
It is only enabled for screens that have the
Egbert Eich's avatar
Egbert Eich committed
608
609
610
611
.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
612
613
This sets the pixmap format to use for depth 24.
Allowed values for
Egbert Eich's avatar
Egbert Eich committed
614
.I bpp
Branden Robinson's avatar
Branden Robinson committed
615
616
617
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
618
619
.TP 7
.BI "Option \*qPC98\*q  \*q" boolean \*q
Branden Robinson's avatar
Branden Robinson committed
620
621
622
623
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.
Egbert Eich's avatar
Egbert Eich committed
624
625
626
627
628
629
630
631
632
.\" Doubt this should be documented.
.ig
.TP 7
.BI "Option \*qEstimateSizesAggressively\*q  \*q" value \*q
This option affects the way that bus resource sizes are estimated.
Default: 0.
..
.TP 7
.BI "Option \*qNoPM\*q  \*q" boolean \*q
Branden Robinson's avatar
Branden Robinson committed
633
634
Disables something to do with power management events.
Default: PM enabled on platforms that support it.
Egbert Eich's avatar
Egbert Eich committed
635
636
.TP 7
.BI "Option \*qXinerama\*q  \*q" boolean \*q
Branden Robinson's avatar
Branden Robinson committed
637
638
enable or disable XINERAMA extension.
Default is disabled.
Egbert Eich's avatar
Egbert Eich committed
639
640
641
.TP 7
.BI "Option \*qAllowDeactivateGrabs\*q \*q" boolean \*q
This option enables the use of the
Branden Robinson's avatar
Branden Robinson committed
642
643
644
.B Ctrl+Alt+Keypad\-Divide
key sequence to deactivate any active keyboard and mouse grabs.
Default: off.
Egbert Eich's avatar
Egbert Eich committed
645
646
647
.TP 7
.BI "Option \*qAllowClosedownGrabs\*q \*q" boolean \*q
This option enables the use of the
Branden Robinson's avatar
Branden Robinson committed
648
649
650
651
652
653
654
.B Ctrl+Alt+Keypad\-Multiply
key sequence to kill clients with an active keyboard or mouse grab as well
as killing any application that may have locked the server, normally using
the
.BR XGrabServer(__libmansuffix__)
Xlib function.
Default: off.
Egbert Eich's avatar
Egbert Eich committed
655
656
.br
Note that the options
Branden Robinson's avatar
Branden Robinson committed
657
.B AllowDeactivateGrabs
Egbert Eich's avatar
Egbert Eich committed
658
and
Branden Robinson's avatar
Branden Robinson committed
659
.B AllowClosedownGrabs
Egbert Eich's avatar
Egbert Eich committed
660
will allow users to remove the grab used by screen saver/locker programs.
Branden Robinson's avatar
Branden Robinson committed
661
662
663
An API was written to such cases.
If you enable this option, make sure your screen saver/locker is updated.
Default: off.
Egbert Eich's avatar
Egbert Eich committed
664
665
666
667
668
.TP 7
.BI "Option \*qHandleSpecialKeys\*q \*q" when \*q
This option controls when the server uses the builtin handler to process
special key combinations (such as
.BR Ctrl+Alt+Backspace ).
Branden Robinson's avatar
Branden Robinson committed
669
670
671
672
Normally the XKEYBOARD extension keymaps will provide mappings for each of
the special key combinations, so the builtin handler is not needed unless
the XKEYBOARD extension is disabled.
The value of
Egbert Eich's avatar
Egbert Eich committed
673
674
675
676
677
678
.I when
can be
.BR Always ,
.BR Never ,
or
.BR WhenNeeded .
Branden Robinson's avatar
Branden Robinson committed
679
680
Default: Use the builtin handler only if needed.
The server will scan the keymap for a mapping to the
Egbert Eich's avatar
Egbert Eich committed
681
682
683
.B Terminate
action and, if found, use XKEYBOARD for processing actions, otherwise
the builtin handler will be used.
684
685
686
.TP 7
.BI "Option \*qAIGLX\*q \*q" boolean \*q
enable or disable AIGLX. AIGLX is enabled by default.
687
.TP 7
688
689
690
691
692
693
694
695
696
697
698
.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
699
700
701
702
703
.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
704
705
706
.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.
Branden Robinson's avatar
Branden Robinson committed
707
.SH "MODULE SECTION"
Egbert Eich's avatar
Egbert Eich committed
708
709
710
711
712
The
.B Module
section is used to specify which __xservername__ server modules should be loaded.
This section is ignored when the __xservername__ server is built in static form.
The types of modules normally loaded in this section are __xservername__ server
Branden Robinson's avatar
Branden Robinson committed
713
714
715
extension modules, and font rasteriser modules.
Most other module types are loaded automatically when they are needed via
other mechanisms.
Egbert Eich's avatar
Egbert Eich committed
716
717
718
719
720
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
721
722
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
723
724
725
726
727
728
729
.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
730
731
732
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
733
734
.PP
.RS 7
735
Example: the FreeType font rasteriser can be loaded with the following entry:
Egbert Eich's avatar
Egbert Eich committed
736
737
.PP
.RS 4
738
.B "Load \*qfreetype\*q"
Egbert Eich's avatar
Egbert Eich committed
739
740
.RE
.RE
741
742
743
744
745
746
747
748
749
750
751
752
753
754
.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.
Egbert Eich's avatar
Egbert Eich committed
755
756
757
758
759
760
761
762
763
764
.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
765
server extensions) can be loaded, with the XFree86\-DGA extension
Egbert Eich's avatar
Egbert Eich committed
766
767
768
769
770
disabled by using the following entry:
.PP
.RS 4
.nf
.B "SubSection \*qextmod\*q"
Branden Robinson's avatar
Branden Robinson committed
771
.B "   Option  \*qomit XFree86\-DGA\*q"
Egbert Eich's avatar
Egbert Eich committed
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
.B EndSubSection
.fi
.RE
.PP
Modules are searched for in each directory specified in the
.B ModulePath
search path, and in the drivers, input, extensions, fonts, and
internal subdirectories of each of those directories.
In addition to this, operating system specific subdirectories of all
the above are searched first if they exist.
.PP
To see what font and extension modules are available, check the contents
of the following directories:
.PP
.RS 4
.nf
__projectroot__/lib/modules/fonts
__projectroot__/lib/modules/extensions
.fi
.RE
.PP
Branden Robinson's avatar
Branden Robinson committed
793
794
795
796
797
798
The \(lqbitmap\(rq font module is loaded automatically.
It is recommended
that at very least the \(lqextmod\(rq extension module be loaded.
If it isn't, some commonly used server extensions (like the SHAPE
extension) will not be available.
.SH "INPUTDEVICE SECTION"
Egbert Eich's avatar
Egbert Eich committed
799
800
The config file may have multiple
.B InputDevice
Branden Robinson's avatar
Branden Robinson committed
801
802
803
804
805
806
sections.
There will normally be at least two: one for the core (primary) keyboard,
and one of the core pointer.
If either of these two is missing, a default configuration for the missing
ones will be used.
Currently the default configuration may not work as expected on all platforms.
Egbert Eich's avatar
Egbert Eich committed
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
.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
828
829
sections.
All other entries are optional.
Egbert Eich's avatar
Egbert Eich committed
830
831
832
.PP
The
.B Identifier
Branden Robinson's avatar
Branden Robinson committed
833
834
entry specifies the unique name for this input device.
The
Egbert Eich's avatar
Egbert Eich committed
835
836
837
838
839
840
.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
841
842
section.
An
Egbert Eich's avatar
Egbert Eich committed
843
844
845
846
847
848
849
850
851
.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
852
853
854
855
The most commonly used input drivers are
.BR keyboard (__drivermansuffix__)
and
.BR mouse (__drivermansuffix__).
Egbert Eich's avatar
Egbert Eich committed
856
857
858
859
860
861
862
.PP
In the absence of an explicitly specified core input device, the first
.B InputDevice
marked as
.B CorePointer
(or
.BR CoreKeyboard )
Branden Robinson's avatar
Branden Robinson committed
863
864
is used.
If there is no match there, the first
Egbert Eich's avatar
Egbert Eich committed
865
.B InputDevice
Branden Robinson's avatar
Branden Robinson committed
866
867
that uses the \(lqmouse\(rq (or \(lqkeyboard\(rq or \(lqkbd\(rq) driver is used.
The final fallback is to use built\-in default configurations.
Egbert Eich's avatar
Egbert Eich committed
868
869
.PP
.B InputDevice
Branden Robinson's avatar
Branden Robinson committed
870
sections recognise some driver\-independent
Egbert Eich's avatar
Egbert Eich committed
871
.BR Options ,
Branden Robinson's avatar
Branden Robinson committed
872
873
874
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
875
876
877
.TP 7
.BI "Option \*qCorePointer\*q"
When this is set, the input device is installed as the core (primary)
Branden Robinson's avatar
Branden Robinson committed
878
879
880
pointer device.
There must be exactly one core pointer.
If this option is not set here, or in the
Egbert Eich's avatar
Egbert Eich committed
881
882
883
884
885
886
887
888
889
890
891
.B ServerLayout
section, or from the
.B \-pointer
command line option, then the first input device that is capable of
being used as a core pointer will be selected as the core pointer.
This option is implicitly set when the obsolete
.B Pointer
section is used.
.TP 7
.BI "Option \*qCoreKeyboard\*q"
When this is set, the input device is to be installed as the core
Branden Robinson's avatar
Branden Robinson committed
892
893
894
(primary) keyboard device.
There must be exactly one core keyboard.
If this option is not set here, in the
Egbert Eich's avatar
Egbert Eich committed
895
896
897
898
899
900
901
902
903
904
905
906
907
.B ServerLayout
section, or from the
.B \-keyboard
command line option, then the first input device that is capable of
being used as a core keyboard will be selected as the core keyboard.
This option is implicitly set when the obsolete
.B Keyboard
section is used.
.TP 7
.BI "Option \*qAlwaysCore\*q  \*q" boolean \*q
.TP 7
.BI "Option \*qSendCoreEvents\*q  \*q" boolean \*q
Both of these options are equivalent, and when enabled cause the
Branden Robinson's avatar
Branden Robinson committed
908
909
910
input device to always report core events.
This can be used, for example, to allow an additional pointer device to
generate core pointer events (like moving the cursor, etc).
Egbert Eich's avatar
Egbert Eich committed
911
912
.TP 4
.BI "Option \*qHistorySize\*q  \*q" number \*q
Branden Robinson's avatar
Branden Robinson committed
913
914
Sets the motion history size.
Default: 0.
Egbert Eich's avatar
Egbert Eich committed
915
916
917
.TP 7
.BI "Option \*qSendDragEvents\*q  \*q" boolean \*q
???
Branden Robinson's avatar
Branden Robinson committed
918
.SH "DEVICE SECTION"
Egbert Eich's avatar
Egbert Eich committed
919
920
The config file may have multiple
.B Device
Branden Robinson's avatar
Branden Robinson committed
921
922
sections.
There must be at least one, for the video card being used.
Egbert Eich's avatar
Egbert Eich committed
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
.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
948
949
entry specifies the unique name for this graphics device.
The
Egbert Eich's avatar
Egbert Eich committed
950
951
952
953
954
955
.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
956
957
section.
A
Egbert Eich's avatar
Egbert Eich committed
958
959
960
961
962
963
.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
964
sections recognise some driver\-independent entries and
Egbert Eich's avatar
Egbert Eich committed
965
.BR Options ,
Branden Robinson's avatar
Branden Robinson committed
966
967
968
969
970
971
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
972
973
974
975
976
977
978
979
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
980
981
982
.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
983
the
Branden Robinson's avatar
Branden Robinson committed
984
.I bus\-id
Egbert Eich's avatar
Egbert Eich committed
985
986
string has the form
.BI PCI: bus : device : function
Branden Robinson's avatar
Branden Robinson committed
987
(e.g., \(lqPCI:1:0:0\(rq might be appropriate for an AGP card).
Egbert Eich's avatar
Egbert Eich committed
988
This field is usually optional in single-head configurations when using
Branden Robinson's avatar
Branden Robinson committed
989
990
991
992
993
994
995
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 __xservername__ server
with the
Egbert Eich's avatar
Egbert Eich committed
996
997
998
999
1000
1001
.B \-scanpci
command line option.
.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
1002
1003
and video memory).
One
Egbert Eich's avatar
Egbert Eich committed
1004
1005
1006
1007
.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
1008
1009
sections applies to.
The legal values of
Egbert Eich's avatar
Egbert Eich committed
1010
1011
1012
1013
1014
1015
.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
1016
1017
1018
1019
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
1020
1021
do.
.TP 7
Branden Robinson's avatar
Branden Robinson committed
1022
.BI "Ramdac  \*q" ramdac\-type \*q
Egbert Eich's avatar
Egbert Eich committed
1023
This optional entry specifies the type of RAMDAC used on the graphics
Branden Robinson's avatar
Branden Robinson committed
1024
1025
1026
1027
1028
1029
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
1030
1031
1032
.TP 7
.BI "DacSpeed  " speed
.TP 7
Branden Robinson's avatar
Branden Robinson committed
1033
.BI "DacSpeed  " "speed\-8 speed\-16 speed\-24 speed\-32"
Egbert Eich's avatar
Egbert Eich committed
1034
This optional entry specifies the RAMDAC speed rating (which is usually
Branden Robinson's avatar
Branden Robinson committed
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
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
1045
1046
.TP 7
.BI "Clocks  " "clock ..."
Branden Robinson's avatar
Branden Robinson committed
1047
1048
1049
1050
1051
1052
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
1053
.B Clocks
Branden Robinson's avatar
Branden Robinson committed
1054
1055
1056
1057
1058
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
1059
.TP
Branden Robinson's avatar
Branden Robinson committed
1060
.BI "ClockChip  \*q" clockchip\-type \*q
Egbert Eich's avatar
Egbert Eich committed
1061
This optional entry is used to specify the clock chip type on graphics
Branden Robinson's avatar
Branden Robinson committed
1062
1063
1064
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
1065
1066
1067
.TP 7
.BI "VideoRam  " "mem"
This optional entry specifies the amount of video ram that is installed
Branden Robinson's avatar
Branden Robinson committed
1068
1069
1070
1071
1072
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
1073
1074
1075
.TP 7
.BI "BiosBase  " "baseaddress"
This optional entry specifies the base address of the video BIOS for
Branden Robinson's avatar
Branden Robinson committed
1076
1077
1078
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
1079
1080
1081
.TP 7
.BI "MemBase  " "baseaddress"
This optional entry specifies the memory base address of a graphics
Branden Robinson's avatar
Branden Robinson committed
1082
1083
1084
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
1085
1086
.TP 7
.BI "IOBase  " "baseaddress"
Branden Robinson's avatar
Branden Robinson committed
1087
1088
1089
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
1090
1091
1092
.TP 7
.BI "ChipID  " "id"
This optional entry specifies a numerical ID representing the chip type.
Branden Robinson's avatar
Branden Robinson committed
1093
1094
1095
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
1096
1097
.TP 7
.BI "ChipRev  " "rev"
Branden Robinson's avatar
Branden Robinson committed
1098
1099
1100
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
1101
1102
1103
.TP 7
.BI "TextClockFreq  " "freq"
This optional entry specifies the pixel clock frequency that is used
Branden Robinson's avatar
Branden Robinson committed
1104
1105
1106
for the regular text mode.
The frequency is specified in MHz.
This is rarely used.
1107
1108
1109
1110
.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
1111
1112
1113
1114
1115
1116
1117
1118
.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
1119
1120
1121
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
1122
1123
1124
1125
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
1126
1127
1128
.SH "VIDEOADAPTOR SECTION"
Nobody wants to say how this works.
Maybe nobody knows ...
Egbert Eich's avatar
Egbert Eich committed
1129

Branden Robinson's avatar
Branden Robinson committed
1130
.SH "MONITOR SECTION"
Egbert Eich's avatar
Egbert Eich committed
1131
1132
The config file may have multiple
.B Monitor
Branden Robinson's avatar
Branden Robinson committed
1133
1134
sections.
There should normally be at least one, for the monitor being used,
Egbert Eich's avatar
Egbert Eich committed
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
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
Branden Robinson's avatar
Branden Robinson committed
1158
1159
entry specifies the unique name for this monitor.
The
Egbert Eich's avatar
Egbert Eich committed
1160
.B Monitor
1161
1162
section may be used to provide information about the specifications of the
monitor, monitor-specific
Egbert Eich's avatar
Egbert Eich committed
1163
.BR Options ,
1164
1165
and information about the video modes to use with the monitor.
.PP
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
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
1176
1177
for a VGA output)
.PP
1178
1179
1180
1181
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
1182
1183
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
Branden Robinson's avatar
Branden Robinson committed
1184
1185
modes available.
When modes are specified explicitly in the
Egbert Eich's avatar
Egbert Eich committed
1186
1187
1188
1189
1190
1191
.B Monitor
section (with the
.BR Modes ,
.BR ModeLine ,
or
.B UseModes
Branden Robinson's avatar
Branden Robinson committed
1192
1193
1194
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.
Egbert Eich's avatar
Egbert Eich committed
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
.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
Branden Robinson's avatar
Branden Robinson committed
1206
.BI "HorizSync  " "horizsync\-range"
Egbert Eich's avatar
Egbert Eich committed
1207
1208
gives the range(s) of horizontal sync frequencies supported by the
monitor.
Branden Robinson's avatar
Branden Robinson committed
1209
.I horizsync\-range
Egbert Eich's avatar
Egbert Eich committed
1210
may be a comma separated list of either discrete values or ranges of
Branden Robinson's avatar
Branden Robinson committed
1211
1212
1213
1214
1215
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
Egbert Eich's avatar
Egbert Eich committed
1216
1217
1218
.B MHz
or
.B Hz
Branden Robinson's avatar
Branden Robinson committed
1219
1220
1221
1222
1223
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.
Egbert Eich's avatar
Egbert Eich committed
1224
.TP 7
Branden Robinson's avatar
Branden Robinson committed
1225
.BI "VertRefresh  " "vertrefresh\-range"
Egbert Eich's avatar
Egbert Eich committed
1226
1227
gives the range(s) of vertical refresh frequencies supported by the
monitor.
Branden Robinson's avatar
Branden Robinson committed
1228
.I vertrefresh\-range
Egbert Eich's avatar
Egbert Eich committed
1229
may be a comma separated list of either discrete values or ranges of
Branden Robinson's avatar
Branden Robinson committed
1230
1231
1232
1233
1234
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
Egbert Eich's avatar
Egbert Eich committed
1235
1236
1237
.B MHz
or
.B kHz
Branden Robinson's avatar
Branden Robinson committed
1238
1239
1240
1241
1242
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.
Egbert Eich's avatar
Egbert Eich committed
1243
1244
1245
.TP 7
.BI "DisplaySize  " "width height"
This optional entry gives the width and height, in millimetres, of the
Branden Robinson's avatar
Branden Robinson committed
1246
1247
1248
picture area of the monitor.
If given this is used to calculate the horizontal and vertical pitch (DPI) of
the screen.
Egbert Eich's avatar
Egbert Eich committed
1249
.TP 7
Branden Robinson's avatar
Branden Robinson committed
1250
.BI "Gamma  " "gamma\-value"
Egbert Eich's avatar
Egbert Eich committed
1251
.TP 7
Branden Robinson's avatar
Branden Robinson committed
1252
.BI "Gamma  " "red\-gamma green\-gamma blue\-gamma"
Egbert Eich's avatar
Egbert Eich committed
1253
This is an optional entry that can be used to specify the gamma correction
Branden Robinson's avatar
Branden Robinson committed
1254
1255
1256
1257
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.
Egbert Eich's avatar
Egbert Eich committed
1258
.TP 7
Branden Robinson's avatar
Branden Robinson committed
1259
.BI "UseModes  \*q" modesection\-id \*q
Egbert Eich's avatar
Egbert Eich committed
1260
1261
1262
Include the set of modes listed in the
.B Modes
section called
Branden Robinson's avatar
Branden Robinson committed
1263
.IR modesection\-id.
1264
This makes all of the modes defined in that section available for use by
Egbert Eich's avatar
Egbert Eich committed
1265
1266
1267
1268
this monitor.
.TP 7
.BI "Mode  \*q" name \*q
This is an optional multi-line entry that can be used to provide
Branden Robinson's avatar
Branden Robinson committed
1269
1270
1271
1272
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
Egbert Eich's avatar
Egbert Eich committed
1273
1274
1275
1276
.B Mode
keyword indicates the start of a multi-line video mode description.
The mode description is terminated with the
.B EndMode
Branden Robinson's avatar
Branden Robinson committed
1277
1278
keyword.
The mode description consists of the following entries:
Egbert Eich's avatar
Egbert Eich committed
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
.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
Branden Robinson's avatar
Branden Robinson committed
1314
1315
1316
1317
1318
1319
1320
1321
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.
Egbert Eich's avatar
Egbert Eich committed
1322
1323
1324
.TP 4
.BI "VScan  " vscan
specifies the number of times each scanline is painted on the screen.
Branden Robinson's avatar
Branden Robinson committed
1325
1326
1327
Not all drivers use this information.
Values less than 1 are treated as 1, which is the default.
Generally, the
Egbert Eich's avatar
Egbert Eich committed
1328
1329
1330
1331
1332
.B \*qDoubleScan\*q
.B Flag
mentioned above doubles this value.
.RE
.TP 7
Branden Robinson's avatar
Branden Robinson committed
1333
.BI "ModeLine  \*q" name \*q " mode\-description"
Egbert Eich's avatar
Egbert Eich committed
1334
1335
1336
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.
Branden Robinson's avatar
Branden Robinson committed
1337
1338
1339
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.
Egbert Eich's avatar
Egbert Eich committed
1340
1341
1342
.PP
.RS 7
The
Branden Robinson's avatar
Branden Robinson committed
1343
1344
1345
1346
1347
1348
1349
1350
.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
Egbert Eich's avatar
Egbert Eich committed
1351
1352
1353
1354
1355
.IR hdisp ,
.IR hsyncstart ,
.IR hsyncend ,
and
.I htotal
Branden Robinson's avatar
Branden Robinson committed
1356
1357
1358
1359
values.
The third section is a list of four numbers specifying the vertical
timings.
These numbers are the
Egbert Eich's avatar
Egbert Eich committed
1360
1361
1362
1363
1364
.IR vdisp ,
.IR vsyncstart ,
.IR vsyncend ,
and
.I vtotal
Branden Robinson's avatar
Branden Robinson committed
1365
1366
1367
values.
The final section is a list of flags specifying other characteristics of
the mode.
Egbert Eich's avatar
Egbert Eich committed
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
.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
Branden Robinson's avatar
Branden Robinson committed
1386
1387
may be used to select the composite sync polarity.
The
Egbert Eich's avatar
Egbert Eich committed
1388
1389
1390
1391
1392
1393
1394
1395
.B HSkew
and
.B VScan
options mentioned above in the
.B Modes
entry description can also be used here.
.RE
.TP 7
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
.BI "Option " "\*qDPMS\*q  " \*qbool\*q
This option controls whether the server should enable the DPMS extension
for power management for this screen.  The default is to enable the
extension.
.TP 7
.BI "Option " "\*qSyncOnGreen\*q  " \*qbool\*q
This option controls whether the video card should drive the sync signal
on the green color pin.  Not all cards support this option, and most
monitors do not require it.  The default is off.
.TP 7
.BI "Option " "\*qTargetRefresh\*q  " \*qrate\*q
This optional entry specifies the vertical refresh rate that the server
should aim for when selecting video modes.  Without this option, the
default is to prefer modes with higher refresh rates.
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
.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  " \*qmonitor\*q
This optional entry specifies that the monitor should be positioned to the
left of the monitor of the given name.
(RandR 1.2-supporting drivers only)
.TP 7
.BI "Option " "\*qRightOf\*q  " \*qmonitor\*q
This optional entry specifies that the monitor should be positioned to the
right of the monitor of the given name.
(RandR 1.2-supporting drivers only)
.TP 7
.BI "Option " "\*qAbove\*q  " \*qmonitor\*q
This optional entry specifies that the monitor should be positioned above the
monitor of the given name.
(RandR 1.2-supporting drivers only)
.TP 7
.BI "Option " "\*qBelow\*q  " \*qmonitor\*q
This optional entry specifies that the monitor should be positioned below the
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)
Egbert Eich's avatar
Egbert Eich committed
1466

Branden Robinson's avatar
Branden Robinson committed
1467
.SH "MODES SECTION"
Egbert Eich's avatar
Egbert Eich committed
1468
1469
The config file may have multiple
.B Modes
Branden Robinson's avatar
Branden Robinson committed
1470
1471
1472
sections, or none.
These sections provide a way of defining sets of video modes independently
of the
Egbert Eich's avatar
Egbert Eich committed
1473
1474
1475
1476
1477
1478
.B Monitor
sections.
.B Monitor
sections may include the definitions provided in these sections by
using the
.B UseModes
Branden Robinson's avatar
Branden Robinson committed
1479
1480
keyword.
In most cases the
Egbert Eich's avatar
Egbert Eich committed
1481
.B Modes
Branden Robinson's avatar
Branden Robinson committed
1482
sections are not necessary because the built\-in set of VESA standard modes
Egbert Eich's avatar
Egbert Eich committed
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
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.
Branden Robinson's avatar
Branden Robinson committed
1510
.SH "SCREEN SECTION"
Egbert Eich's avatar
Egbert Eich committed
1511
1512
The config file may have multiple
.B Screen
Branden Robinson's avatar
Branden Robinson committed
1513
1514
1515
sections.
There must be at least one, for the \(lqscreen\(rq being used.
A \(lqscreen\(rq represents the binding of a graphics device
Egbert Eich's avatar
Egbert Eich committed
1516
1517
1518
.RB ( Device
section) and a monitor
.RB ( Monitor
Branden Robinson's avatar
Branden Robinson committed
1519
1520
section).
A
Egbert Eich's avatar
Egbert Eich committed
1521
.B Screen
Branden Robinson's avatar
Branden Robinson committed
1522
section is considered \(lqactive\(rq if it is referenced by an active
Egbert Eich's avatar
Egbert Eich committed
1523
1524
1525
.B ServerLayout
section or by the
.B \-screen
Branden Robinson's avatar
Branden Robinson committed
1526
1527
command line option.
If neither of those is present, the first
Egbert Eich's avatar
Egbert Eich committed
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
.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
Branden Robinson's avatar
Branden Robinson committed
1555
1556
entries are mandatory.
All others are optional.
Egbert Eich's avatar
Egbert Eich committed
1557
1558
1559
.PP
The
.B Identifier
Branden Robinson's avatar
Branden Robinson committed
1560
1561
entry specifies the unique name for this screen.
The
Egbert Eich's avatar
Egbert Eich committed
1562
1563
.B Screen
section provides information specific to the whole screen, including
Branden Robinson's avatar
Branden Robinson committed
1564
screen\-specific
Egbert Eich's avatar
Egbert Eich committed
1565
.BR Options .
Branden Robinson's avatar
Branden Robinson committed
1566
In multi\-head configurations, there will be multiple active
Egbert Eich's avatar
Egbert Eich committed
1567
1568
1569
1570
1571
.B Screen
sections, one for each head.
The entries available
for this section are:
.TP 7
Branden Robinson's avatar
Branden Robinson committed
1572
.BI "Device  \*q" device\-id \*q
Egbert Eich's avatar
Egbert Eich committed
1573
1574
This mandatory entry specifies the
.B Device
Branden Robinson's avatar
Branden Robinson committed
1575
1576
1577
1578
section to be used for this screen.
This is what ties a specific graphics card to a screen.
The
.I device\-id
Egbert Eich's avatar
Egbert Eich committed
1579
1580
1581
1582
1583
1584
must match the
.B Identifier
of a
.B Device
section in the config file.
.TP 7
Branden Robinson's avatar
Branden Robinson committed
1585
.BI "Monitor  \*q" monitor\-id \*q
Egbert Eich's avatar
Egbert Eich committed
1586
1587
1588
specifies which monitor description is to be used for this screen.
If a
.B Monitor
Branden Robinson's avatar
Branden Robinson committed
1589
1590
1591
name is not specified, a default configuration is used.
Currently the default configuration may not function as expected on all
platforms.
Egbert Eich's avatar
Egbert Eich committed
1592
.TP 7
Branden Robinson's avatar
Branden Robinson committed
1593
.BI "VideoAdaptor  \*q" xv\-id \*q
Egbert Eich's avatar
Egbert Eich committed
1594
1595
1596
1597
specifies an optional Xv video adaptor description to be used with this
screen.
.TP 7
.BI "DefaultDepth  " depth
Branden Robinson's avatar
Branden Robinson committed
1598
1599
specifies which color depth the server should use by default.
The
Egbert Eich's avatar
Egbert Eich committed
1600
.B \-depth
Branden Robinson's avatar
Branden Robinson committed
1601
1602
1603
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.
Egbert Eich's avatar
Egbert Eich committed
1604
1605
.TP 7
.BI "DefaultFbBpp  " bpp
Branden Robinson's avatar
Branden Robinson committed
1606
1607
specifies which framebuffer layout to use by default.
The
Egbert Eich's avatar
Egbert Eich committed
1608
.B \-fbbpp
Branden Robinson's avatar
Branden Robinson committed
1609
1610
1611
1612
1613
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.
Egbert Eich's avatar
Egbert Eich committed
1614
1615
1616
1617
1618
1619
.TP 7
.B Options
Various
.B Option
flags may be specified in the
.B Screen
Branden Robinson's avatar
Branden Robinson committed
1620
1621
1622
section.
Some are driver\-specific and are described in the driver documentation.
Others are driver\-independent, and will eventually be described here.
Egbert Eich's avatar
Egbert Eich committed
1623
1624
1625
1626
.\" 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
Branden Robinson's avatar
Branden Robinson committed
1627
1628
1629
1630
1631
1632
1633
1634
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).
Egbert Eich's avatar
Egbert Eich committed
1635
1636
.TP 7
.BI "Option \*qInitPrimary\*q \*q" boolean \*q
Branden Robinson's avatar
Branden Robinson committed
1637
1638
Use the Int10 module to initialize the primary graphics card.
Normally, only secondary cards are soft-booted using the Int10 module, as the
Egbert Eich's avatar
Egbert Eich committed
1639
1640
1641
1642
1643
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
Branden Robinson's avatar
Branden Robinson committed
1644
1645
of the graphics card to initialize it.
Default: false.
Egbert Eich's avatar
Egbert Eich committed
1646
1647
1648
1649
1650
1651
1652
1653
1654
.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
Branden Robinson's avatar
Branden Robinson committed
1655
stored in system memory (using a memory\-mapped aperture).
Egbert Eich's avatar
Egbert Eich committed
1656
1657
.TP 7
.BI "Option \*qXaaNoColor8x8PatternFillRect\*q"
Branden Robinson's avatar
Branden Robinson committed
1658
Disables accelerated fills of a rectangular region with a full\-color
Egbert Eich's avatar
Egbert Eich committed
1659
1660
1661
pattern.
.TP 7
.BI "Option \*qXaaNoColor8x8PatternFillTrap\*q"