source: x/installing/xorg-config.xml@ b0b84b62

11.2 plabs/python-mods trunk xry111/soup3
Last change on this file since b0b84b62 was b0b84b62, checked in by Bruce Dubbs <bdubbs@…>, 4 months ago

Fix some typos and use gz for icewm

  • Property mode set to 100644
File size: 16.9 KB
1<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
2 "" [
3 <!ENTITY % general-entities SYSTEM "../../general.ent">
4 %general-entities;
7<sect1 id="xorg-config">
8 <?dbhtml filename="xorg-config.html"?>
10 <sect1info>
11 <date>$Date$</date>
12 </sect1info>
14 <title>Xorg-&xorg-version; Testing and Configuration</title>
16 <indexterm zone="xorg-config">
17 <primary sortas="g-configuring-xorg">Configuring Xorg</primary>
18 </indexterm>
20 <sect2 id='X11-testing' xreflabel="Testing Xorg">
21 <title>Testing Xorg</title>
23 <note>
24 <para>
25 Before starting Xorg for the first time, is is useful to
26 rebuild the library cache by running <userinput>ldconfig</userinput>
27 as the <systemitem class="username">root</systemitem> user.
28 </para>
29 </note>
31 <note>
32 <para>
33 Before starting Xorg for the first time, is is often needed to
34 reboot the system to ensure all appropriate daemons are started
35 and appropriate security issues are properly set.
36 As an alternative, logging out and logging back in may work, but as
37 of this writing has not been tested.
38 </para>
39 </note>
41 <warning>
42 <para>
43 If Xorg hangs for some reason (for example, lacking a proper
44 input driver), the system may stop responding to any user input.
45 As a precaution, you can enable a magic <keycap>SysRq</keycap> key
46 before testing Xorg. As the
47 <systemitem class="username">root</systemitem> user, issue:
48 </para>
50<screen><userinput>echo 4 > /proc/sys/kernel/sysrq</userinput></screen>
52 <para>
53 Then if Xorg hangs, it's possible to use
54 <keycombo>
55 <keycap>Alt</keycap>
56 <keycap>SysRq</keycap>
57 <keycap>R</keycap>
58 </keycombo>
59 to reset the keyboard mode. Now it should be able to use
60 <keycombo>
61 <keycap>Ctrl</keycap>
62 <keycap>Alt</keycap>
63 <keycap>Fx</keycap>
64 </keycombo>
65 (replace x with a VT number) to switch to another VT.
66 If it works, login and kill Xorg using command line in the new VT.
67 </para>
68 </warning>
70 <para>
71 To test the <application>Xorg</application> installation, issue
72 <command>startx</command>. This command brings up a rudimentary window
73 manager called <emphasis>twm</emphasis> with three xterm windows and one
74 xclock window. The xterm window in the upper left is a login terminal and
75 running <emphasis>exit</emphasis> from this terminal will exit the
76 <application>X Window</application> session. The third xterm window may
77 be obscured on your system by the other two xterms.
78 </para>
80 <note>
81 <para>
82 When testing <application>Xorg</application> with the
83 <application>twm</application> window manager, there will be several
84 warnings in the Xorg log file, <!--<filename revision="sysv">
85 /var/log/Xorg.0.log</filename><filename revision="systemd">-->
86 $HOME/.local/share/xorg/Xorg.0.log<!--</filename>-->, about missing font
87 files. In addition, there will be several warnings on the text mode
88 terminal (usually tty1) about missing fonts. These warnings do not
89 affect functionality, but can be removed if desired by installing
90 the <xref linkend="xorg7-legacy"/>.
91 </para>
92 </note>
94 <para>
95 Generally, there is no specific configuration required for
96 <application>Xorg</application>, but customization is possible. For
97 details, see <xref linkend='xconfig'/> below.
98 </para>
100 </sect2>
102 <sect2 role="configuration" id="checking-dri" xreflabel="Checking the DRI
103 installation">
104 <title>Checking the Direct Rendering Infrastructure (DRI)
105 Installation</title>
107 <para>
108 DRI is a framework for allowing software to access graphics hardware in
109 a safe and efficient manner. It is installed in
110 <application>X</application> by default (using
111 <application>Mesa</application>) if you have a supported video card.
112 </para>
114 <para>
115 To check if DRI drivers are installed properly, check the log file
116 <filename>$HOME/.local/share/xorg/Xorg.0.log</filename> (or
117 <filename>/var/log/Xorg.0.log</filename> if you have
118 built <xref linkend="xorg-server"/> with the suid bit) for
119 statements such as:
120 </para>
122<screen><literal>(II) intel(0): direct rendering: DRI2 Enabled</literal></screen>
124 <para>or</para>
126<screen><literal>(II) NOUVEAU(0): Loaded DRI module</literal></screen>
128 <note>
129 <para>
130 DRI configuration may differ if you are using alternate drivers, such
131 as those from
132 <ulink url="">NVIDIA</ulink> or
133 <ulink url="">AMD</ulink>.
134 </para>
135 </note>
137<!-- With elogind, this is not needed anymore
138 <para>
139 Although all users can use software acceleration, any hardware
140 acceleration (DRI2) is only available to <systemitem
141 class="username">root</systemitem> and members of the <systemitem
142 class="groupname">video</systemitem> group, but
143 <phrase revision="sysv"><emphasis>ConsoleKit2</emphasis></phrase>
144 <phrase revision="systemd"><emphasis>systemd-logind</emphasis></phrase>
145 takes care of adding any logged in user to the user ACL's of
146 <filename>/dev/dri/card*</filename>, the special file(s) allowing access
147 to hardware acceleration.<phrase revision="systemd"> So, no further
148 configuration is needed.</phrase>
149 </para>
151 <para revision="sysv">
152 If your driver is supported and <emphasis>ConsoleKit2</emphasis> is not
153 installed, add any users that might use X to the <systemitem
154 class="groupname">video</systemitem> group:
155 </para>
157<screen role="root" revision="sysv"><userinput>usermod -a -G video <replaceable>&lt;username&gt;</replaceable></userinput></screen>
159 <para>
160 Another way to determine if DRI is working properly is to use one of the
161 two optionally installed OpenGL demo programs in <xref
162 linkend="mesa"/>. From an X terminal, run <command>glxinfo</command>
163 and look for the phrase:
164 </para>
166<screen><computeroutput>name of display: :0
167display: :0 screen: 0
168direct rendering: Yes</computeroutput></screen>
170 <para>
171 If direct rendering is enabled, you can add verbosity by running
172 <command>LIBGL_DEBUG=verbose glxinfo</command>. This will show the
173 drivers, device nodes and files used by the DRI system.
174 </para>
176 <para>
177 To confirm that DRI2 hardware acceleration is working, you can (still in
178 the X terminal) run the command <command>glxinfo | grep -E "(OpenGL
179 vendor|OpenGL renderer|OpenGL version)"</command>.
180 If that reports something <emphasis>other than</emphasis>
181 <literal>Software Rasterizer</literal> then you have working
182 acceleration for the user who ran the command.
183 </para>
185 <para>
186 If your hardware does not have any DRI2 driver available, it will use a
187 Software Rasterizer for Direct Rendering. In such cases, you can use a
188 new, LLVM-accelerated, Software Rasterizer called LLVMPipe. In order to
189 build LLVMPipe just make sure that <xref linkend="llvm"/> is present at
190 Mesa build time. Note that all decoding is done on the CPU instead of
191 the GPU, so the display will run slower than with hardware acceleration.
192 To check if you are using LLVMpipe, review the output of the glxinfo
193 command above. An example of the output using the Software Rasterizer
194 is shown below:
195 </para>
197<screen><computeroutput>OpenGL vendor string: VMware, Inc.
198OpenGL renderer string: Gallium 0.4 on llvmpipe (LLVM 3.5, 256 bits)
199OpenGL version string: 3.0 Mesa 10.4.5</computeroutput></screen>
201 <para>
202 You can also force LLVMPipe by exporting the
203 <envar>LIBGL_ALWAYS_SOFTWARE=1</envar> environment variable when
204 starting Xorg.
205 </para>
207 <para>
208 Again, if you have built the Mesa OpenGL demos, you can also run the test
209 program <command>glxgears</command>. This program brings up a window with
210 three gears turning. The X terminal will display how many frames were
211 drawn every five seconds, so this will give a rough benchmark. The window
212 is scalable, and the frames drawn per second is highly dependent on the
213 size of the window. On some hardware, <command>glxgears</command> will
214 run synchronized with the vertical refresh signal and the frame rate will
215 be approximately the same as the monitor refresh rate.
216 </para>
218 </sect2>
220 <sect2 role="configuration" id="xorg-debug" xreflabel="Debugging Xorg">
221 <title>Debugging Xorg</title>
223 <para>
224 When starting xorg, there are a couple of ways to check what any
225 issues you may have. If the system comes up, you can see what driver
226 is being used by running <command>xdriinfo</command>. If there are
227 issues or you just want to check, look at <filename>Xorg.0.log</filename>.
228 </para>
230 <para>
231 The location of <filename>Xorg.0.log</filename> depends on how Xorg is
232 installed. If the instructions in the book are followed closely and
233 Xorg is started from the command line, it will be located in the
234 <filename class="directory">$HOME/.local/share/xorg/</filename> directory.
235 If Xorg is started by a display manager (e.g. <xref linkend='lightdm'/>,
236 <xref linkend='lxdm'/>, or <xref linkend='gdm'/>) or if
237 <filename>$XORG_PREFIX/libexec/Xorg</filename> has the suid bit set,
238 it will be located in the <filename class="directory">/var/log/</filename>
239 directory.
240 </para>
242 <bridgehead renderas="sect3">Xorg.0.log Issues</bridgehead>
244 <para>
245 When you look at Xorg.0.log, check for entries like (EE) or (WW).
246 Below are some common entries:
247 </para>
249 <bridgehead renderas="sect5">(WW) Open ACPI failed (/var/run/acpid.socket)</bridgehead>
251 <para>
252 This warning is becasue <xref linkend='acpid'/> is not installed. If you
253 are not on a laptop, it can be safely ignored. On a laptop, install
254 <xref linkend='acpid'/> to enable actions like recognizing when the lid is
255 closed.
256 </para>
258 <bridgehead renderas="sect5">(WW) VGA arbiter: cannot open kernel arbiter, no multi-card support</bridgehead>
260 <para>
261 This warning is displayed when a regular user starts Xorg. The library
262 <filename></filename> issues this warning when it
263 tries to open <filename>/dev/vga_arbiter</filename>. If there is only
264 one video card in the system, it can safely be ignored. If desired, the
265 permissions of this device can be changed by adding a udev rule and
266 adding the local user to the video group. As the &root; user:
267 </para>
269<screen role="root"><userinput>cat > /etc/udev/rules.d/99-vga-arbiter.rules &lt;&lt; EOF
270# /etc/udev/rules.d/99-vga-arbiter.rules: Set vga_arbiter group/mode
272ACTION=="add", KERNEL=="vga_arbiter", GROUP="video" MODE="0660"
275usermod -a -G video &lt;user running xorg&gt;</userinput></screen>
277 <bridgehead renderas="sect5">(EE) AIGLX error: dlopen of /opt/xorg/lib/dri/ failed</bridgehead>
279 <para>
280 This error, accompanied by (EE) AIGLX error: unable to load driver i965, occurs
281 in some systems with Intel based graphics devices. It is caused by a mismatch
282 between the current <xref linkend='xorg-server'/> and <xref linkend='mesa'/>. Xorg
283 no longer uses the i965 driver and uses the crocus or iris mesa drivers as
284 indicated by the <command>xdriinfo</command> command. It can safely be ignored.
285 </para>
287 <para>
288 If desired, this warning can be removed by commenting out lines
289 330-331 and 337-338 (LogMessage) of
290 <filename>glx/glxdricommon.c</filename> in the <xref linkend='xorg-server'/>
291 package.
292 </para>
294 </sect2>
296 <sect2 role="configuration" id="hybrid-graphics" xreflabel="Hybrid Graphics">
297 <title>Hybrid Graphics</title>
299 <para>
300 Hybrid Graphics is still in experimental state for Linux. Xorg Developers
301 have developed a technology called PRIME that can be used for switching
302 between integrated and muxless discrete GPU at will. Automatic switching
303 is not possible at the moment.
304 </para>
306 <para>
307 In order to use PRIME for GPU switching, make sure that you are using
308 Linux Kernel 3.4 or later (recommended). You will need latest DRI and
309 DDX drivers for your hardware and <application>Xorg Server</application>
310 1.13 or later.
311 </para>
313 <para>
314 <application>Xorg Server</application> should load both GPU drivers
315 automaticaly. You can check that by running:
316 </para>
318<screen><userinput>xrandr --listproviders</userinput></screen>
320 <para>
321 There should be two (or more) providers listed, for example:
322 </para>
324<screen><computeroutput>Providers: number : 2
325Provider 0: id: 0x7d cap: 0xb, Source Output, Sink Output, Sink Offload crtcs: 3 outputs: 4 associated providers: 1 name:Intel
326Provider 1: id: 0x56 cap: 0xf, Source Output, Sink Output, Source Offload, Sink Offload crtcs: 6 outputs: 1 associated providers: 1 name:radeon</computeroutput></screen>
328 <para>
329 In order to be able to run a GLX application on a discrete GPU, you will
330 need to run the following command, where &lt;provider&gt; is the more
331 powerful discrete card, and &lt;sink&gt; is the card which has a display
332 connected:
333 </para>
335<screen><userinput>xrandr --setprovideroffloadsink <replaceable>&lt;provider&gt; &lt;sink&gt;</replaceable></userinput></screen>
337 <note>
338 <para>
339 With newer <application>Xorg</application> drivers, such as modesetting
340 or intel, which are DRI3 capable, the above command is no longer
341 necessary. It does no harm however.
342 </para>
343 </note>
345 <para>
346 Then, you will need to export the <envar>DRI_PRIME=1</envar> environment
347 variable each time you want the powerful GPU to be used. For example,
349<screen><userinput>DRI_PRIME=1 glxinfo | grep -E "(OpenGL vendor|OpenGL renderer|OpenGL version)"</userinput></screen>
351 will show OpenGL vendor, renderer and version for the discrete GPU.
352 </para>
354 <para>
355 If the last command reports same OpenGL renderer with and without
356 <envar>DRI_PRIME=1</envar>, you will need to check your installation.
357 </para>
359 </sect2>
361 <sect2 role="configuration" id='xconfig'>
362 <title>Setting up Xorg Devices</title>
364 <para>
365 For most hardware configurations, modern Xorg will automatically
366 get the server configuration correct without any user intervention. There
367 are, however, some cases where auto-configuration will be incorrect.
368 Following are some example manual configuration items that may be of use
369 in these instances.
370 </para>
372 <sect3 id="xinput">
373 <title>Setting up X Input Devices</title>
374 <para>
375 For most input devices, no additional configuration will be
376 necessary. This section is provided for informational purposes only.
377 </para>
379 <para>
380 A sample default XKB setup could look like the following (executed as
381 the <systemitem class="username">root</systemitem> user):
382 </para>
384<screen role="root"><userinput>cat &gt; /etc/X11/xorg.conf.d/xkb-defaults.conf &lt;&lt; "EOF"
385<literal>Section "InputClass"
386 Identifier "XKB Defaults"
387 MatchIsKeyboard "yes"
388 Option "XkbLayout" "fr"
389 Option "XkbOptions" "terminate:ctrl_alt_bksp"
393 <para>
394 The <quote>XkbLayout</quote> line is an example for a French (AZERTY)
395 keyboard. Change it to your keyboard model. That line is not needed for
396 a QWERTY (US) keyboard.
397 </para>
398 </sect3>
400 <sect3 id="xdisplay">
401 <title>Fine Tuning Display Settings</title>
403 <para>
404 Again, with modern Xorg, little or no additional configuration is
405 necessary. If you should need extra options passed to your video driver,
406 for instance, you could use something like the following (again,
407 executed as the <systemitem class="username">root</systemitem> user):
408 </para>
410<screen role="root"><userinput>cat &gt; /etc/X11/xorg.conf.d/videocard-0.conf &lt;&lt; "EOF"
411<literal>Section "Device"
412 Identifier "Videocard0"
413 Driver "radeon"
414 VendorName "Videocard vendor"
415 BoardName "ATI Radeon 7500"
416 Option "NoAccel" "true"
420 <para>
421 Another common setup is having multiple server layouts for use in
422 different environments. Though the server will automatically detect the
423 presence of another monitor, it may get the order incorrect:
424 </para>
426<screen role="root"><userinput>cat &gt; /etc/X11/xorg.conf.d/server-layout.conf &lt;&lt; "EOF"
427<literal>Section "ServerLayout"
428 Identifier "DefaultLayout"
429 Screen 0 "Screen0" 0 0
430 Screen 1 "Screen1" LeftOf "Screen0"
431 Option "Xinerama"
435 </sect3>
436 </sect2>
Note: See TracBrowser for help on using the repository browser.