source: x/installing/xorg-config.xml@ 5f729f8

<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;
]>

<sect1 id="xorg-config">
  <?dbhtml filename="xorg-config.html"?>

  <sect1info>
    <date>$Date$</date>
  </sect1info>

  <title>Xorg-&xorg-version; Testing and Configuration</title>

  <indexterm zone="xorg-config">
    <primary sortas="g-configuring-xorg">Configuring Xorg</primary>
  </indexterm>

  <sect2 id='X11-testing' xreflabel="Testing Xorg">
    <title>Testing Xorg</title>

    <note>
      <para>
        Before starting Xorg for the first time, is is useful to
        rebuild the library cache by running <userinput>ldconfig</userinput>
        as the <systemitem class="username">root</systemitem> user.
      </para>
    </note>

    <note>
      <para>
        Before starting Xorg for the first time, is is often needed to
        reboot the system to ensure all appropriate daemons are started
        and appropriate security issues are properly set.
        As an alternative, logging out and logging back in may work, but as
        of this writing has not been tested.
      </para>
    </note>

    <warning>
      <para>
        If Xorg hangs for some reason (for example, lacking a proper
        input driver), the system may stop responding to any user input.
        As a precaution, you can enable a magic <keycap>SysRq</keycap> key
        before testing Xorg.  As the
        <systemitem class="username">root</systemitem> user, issue:
      </para>

<screen><userinput>echo 4 > /proc/sys/kernel/sysrq</userinput></screen>

      <para>
        Then if Xorg hangs, it's possible to use
        <keycombo>
          <keycap>Alt</keycap>
          <keycap>SysRq</keycap>
          <keycap>R</keycap>
        </keycombo>
        to reset the keyboard mode.  Now it should be able to use
        <keycombo>
          <keycap>Ctrl</keycap>
          <keycap>Alt</keycap>
          <keycap>Fx</keycap>
        </keycombo>
        (replace x with a VT number) to switch to another VT.
                If it works, login and kill Xorg using command line in the new VT.
      </para>
    </warning>

    <para>
      To test the <application>Xorg</application> installation, issue
      <command>startx</command>. This command brings up a rudimentary window
      manager called <emphasis>twm</emphasis> with three xterm windows and one
      xclock window.  The xterm window in the upper left is a login terminal and
      running <emphasis>exit</emphasis> from this terminal will exit the
      <application>X Window</application> session.  The third xterm window may
      be obscured on your system by the other two xterms.
    </para>

    <note>
      <para>
        When testing <application>Xorg</application> with the
        <application>twm</application> window manager, there will be several
        warnings in the Xorg log file, <!--<filename revision="sysv">
        /var/log/Xorg.0.log</filename><filename revision="systemd">-->
        $HOME/.local/share/xorg/Xorg.0.log<!--</filename>-->, about missing font
        files. In addition, there will be several warnings on the text mode
        terminal (usually tty1) about missing fonts. These warnings do not
        affect functionality, but can be removed if desired by installing
        the <xref linkend="xorg7-legacy"/>.
      </para>
    </note>

    <para>
      Generally, there is no specific configuration required for
      <application>Xorg</application>, but customization is possible. For
      details, see <xref linkend='xconfig'/> below.
    </para>

  </sect2>

  <sect2 role="configuration" id="checking-dri" xreflabel="Checking the DRI
  installation">
    <title>Checking the Direct Rendering Infrastructure (DRI)
    Installation</title>

    <para>
      DRI is a framework for allowing software to access graphics hardware in
      a safe and efficient manner. It is installed in
      <application>X</application> by default (using
      <application>Mesa</application>) if you have a supported video card.
    </para>

    <para>
      To check if DRI drivers are installed properly, check the log file
      <filename>$HOME/.local/share/xorg/Xorg.0.log</filename> (or
      <filename>/var/log/Xorg.0.log</filename> if you have
      built <xref linkend="xorg-server"/> with the suid bit) for
      statements such as:
    </para>

<screen><literal>(II) intel(0): direct rendering: DRI2 Enabled</literal></screen>

    <para>or</para>

<screen><literal>(II) NOUVEAU(0): Loaded DRI module</literal></screen>

    <note>
      <para>
        DRI configuration may differ if you are using alternate drivers, such
        as those from
        <ulink url="http://www.nvidia.com/page/home.html">NVIDIA</ulink> or
        <ulink url="http://www.amd.com/">AMD</ulink>.
      </para>
    </note>

<!-- With elogind, this is not needed anymore
    <para>
      Although all users can use software acceleration, any hardware
      acceleration (DRI2) is only available to <systemitem
      class="username">root</systemitem> and members of the <systemitem
      class="groupname">video</systemitem> group, but
      <phrase revision="sysv"><emphasis>ConsoleKit2</emphasis></phrase>
      <phrase revision="systemd"><emphasis>systemd-logind</emphasis></phrase>
      takes care of adding any logged in user to the user ACL's of
      <filename>/dev/dri/card*</filename>, the special file(s) allowing access
      to hardware acceleration.<phrase revision="systemd"> So, no further
      configuration is needed.</phrase>
    </para>

    <para revision="sysv">
      If your driver is supported and <emphasis>ConsoleKit2</emphasis> is not
      installed, add any users that might use X to the <systemitem
      class="groupname">video</systemitem> group:
    </para>

<screen role="root" revision="sysv"><userinput>usermod -a -G video <replaceable>&lt;username&gt;</replaceable></userinput></screen>
-->
    <para>
      Another way to determine if DRI is working properly is to use one of the
      two optionally installed OpenGL demo programs in <xref
      linkend="mesa"/>. From an X terminal, run <command>glxinfo</command>
      and look for the phrase:
    </para>

<screen><computeroutput>name of display: :0
display: :0  screen: 0
direct rendering: Yes</computeroutput></screen>

    <para>
      If direct rendering is enabled, you can add verbosity by running
      <command>LIBGL_DEBUG=verbose glxinfo</command>. This will show the
      drivers, device nodes and files used by the DRI system.
    </para>

    <para>
      To confirm that DRI2 hardware acceleration is working, you can (still in
      the X terminal) run the command <command>glxinfo | grep -E "(OpenGL
      vendor|OpenGL renderer|OpenGL version)"</command>.
      If that reports something <emphasis>other than</emphasis>
      <literal>Software Rasterizer</literal> then you have working
      acceleration for the user who ran the command.
    </para>

    <para>
      If your hardware does not have any DRI2 driver available, it will use a
      Software Rasterizer for Direct Rendering. In such cases, you can use a
      new, LLVM-accelerated, Software Rasterizer called LLVMPipe. In order to
      build LLVMPipe just make sure that <xref linkend="llvm"/> is present at
      Mesa build time. Note that all decoding is done on the CPU instead of
      the GPU, so the display will run slower than with hardware acceleration.
      To check if you are using LLVMpipe, review the output of the glxinfo
      command above.  An example of the output using the Software Rasterizer
      is shown below:
    </para>

<screen><computeroutput>OpenGL vendor string: VMware, Inc.
OpenGL renderer string: Gallium 0.4 on llvmpipe (LLVM 3.5, 256 bits)
OpenGL version string: 3.0 Mesa 10.4.5</computeroutput></screen>

    <para>
      You can also force LLVMPipe by exporting the
      <envar>LIBGL_ALWAYS_SOFTWARE=1</envar> environment variable when
      starting Xorg.
    </para>

    <para>
      Again, if you have built the Mesa OpenGL demos, you can also run the test
      program <command>glxgears</command>. This program brings up a window with
      three gears turning. The X terminal will display how many frames were
      drawn every five seconds, so this will give a rough benchmark. The window
      is scalable, and the frames drawn per second is highly dependent on the
      size of the window. On some hardware, <command>glxgears</command> will
      run synchronized with the vertical refresh signal and the frame rate will
      be approximately the same as the monitor refresh rate.
    </para>

  </sect2>

  <sect2 role="configuration" id="xorg-debug" xreflabel="Debugging Xorg">
    <title>Debugging Xorg</title>

    <para>
      When starting xorg, there are a couple of ways to check what any
      issues you may have.  If the system comes up, you can see what driver
      is being used by running <command>xdriinfo</command>. If there are
      issues or you just want to check, look at <filename>Xorg.0.log</filename>.
    </para>

    <para>
      The location of <filename>Xorg.0.log</filename> depends on how Xorg is
      installed.  If the instructions in the book are followed closely and 
      Xorg is started from the command line, it will be located in the 
      <filename class="directory">$HOME/.local/share/xorg/</filename> directory.
      If Xorg is started by a display manager (e.g. <xref linkend='lightdm'/>,
      <xref linkend='lxdm'/>, or <xref linkend='gdm'/>) or if 
      <filename>$XORG_PREFIX/libexec/Xorg</filename> has the suid bit set,
      it will be located in the <filename class="directory">/var/log/</filename>
      directory.
    </para>

    <bridgehead renderas="sect3">Xorg.0.log Issues</bridgehead>

    <para>
      When you look at Xorg.0.log, check for entries like (EE) or (WW).
      Below are some common entries:
    </para>

    <bridgehead renderas="sect5">(WW) Open ACPI failed (/var/run/acpid.socket)</bridgehead>

    <para>
      This warning is because <xref linkend='acpid'/> is not installed. If you
      are not on a laptop, it can be safely ignored. On a laptop, install
      <xref linkend='acpid'/> to enable actions like recognizing when the lid is
      closed.
    </para>

    <bridgehead renderas="sect5">(WW) VGA arbiter: cannot open kernel arbiter, no multi-card support</bridgehead>

    <para>
      This warning is displayed when a regular user starts Xorg.  The library
      <filename>libpciaccess.so</filename> issues this warning when it
      tries to open <filename>/dev/vga_arbiter</filename>.  If there is only 
      one video card in the system, it can safely be ignored. If desired, the
      permissions of this device can be changed by adding a udev rule and 
      adding the local user to the video group. As the &root; user:
    </para>

<screen role="root"><userinput>cat > /etc/udev/rules.d/99-vga-arbiter.rules &lt;&lt; EOF
# /etc/udev/rules.d/99-vga-arbiter.rules: Set vga_arbiter group/mode

ACTION=="add", KERNEL=="vga_arbiter", GROUP="video" MODE="0660"
EOF

usermod -a -G video &lt;user running xorg&gt;</userinput></screen>

    <bridgehead renderas="sect5">(EE) AIGLX error: dlopen of /opt/xorg/lib/dri/i965_dri.so failed</bridgehead>

  <para>
    This error, accompanied by (EE) AIGLX error: unable to load driver i965, occurs
    in some systems with Intel based graphics devices.  It is caused by a mismatch
    between the current <xref linkend='xorg-server'/> and <xref linkend='mesa'/>. Xorg
    no longer uses the i965 driver and uses the crocus or iris mesa drivers as
    indicated by the <command>xdriinfo</command> command.  It can safely be ignored.
  </para>

  <para>
    If desired, this warning can be removed by commenting out lines 
    330-331 and 337-338 (LogMessage) of 
    <filename>glx/glxdricommon.c</filename> in the <xref linkend='xorg-server'/>
    package.
  </para>

  </sect2>

  <sect2 role="configuration" id="hybrid-graphics" xreflabel="Hybrid Graphics">
    <title>Hybrid Graphics</title>

    <para>
      Hybrid Graphics is still in experimental state for Linux. Xorg Developers
      have developed a technology called PRIME that can be used for switching
      between integrated and muxless discrete GPU at will. Automatic switching
      is not possible at the moment.
    </para>

    <para>
      In order to use PRIME for GPU switching, make sure that you are using
      Linux Kernel 3.4 or later (recommended). You will need latest DRI and
      DDX drivers for your hardware and <application>Xorg Server</application>
      1.13 or later.
    </para>

    <para>
      <application>Xorg Server</application> should load both GPU drivers
      automatically. You can check that by running:
    </para>

<screen><userinput>xrandr --listproviders</userinput></screen>

    <para>
      There should be two (or more) providers listed, for example:
    </para>

<screen><computeroutput>Providers: number : 2
Provider 0: id: 0x7d cap: 0xb, Source Output, Sink Output, Sink Offload crtcs: 3 outputs: 4 associated providers: 1 name:Intel
Provider 1: id: 0x56 cap: 0xf, Source Output, Sink Output, Source Offload, Sink Offload crtcs: 6 outputs: 1 associated providers: 1 name:radeon</computeroutput></screen>

    <para>
      In order to be able to run a GLX application on a discrete GPU, you will
      need to run the following command, where &lt;provider&gt; is the more
      powerful discrete card, and &lt;sink&gt; is the card which has a display
      connected:
    </para>

<screen><userinput>xrandr --setprovideroffloadsink <replaceable>&lt;provider&gt; &lt;sink&gt;</replaceable></userinput></screen>

    <note>
      <para>
        With newer <application>Xorg</application> drivers, such as modesetting
        or intel, which are DRI3 capable, the above command is no longer
        necessary. It does no harm however.
      </para>
    </note>

    <para>
      Then, you will need to export the <envar>DRI_PRIME=1</envar> environment
      variable each time you want the powerful GPU to be used. For example,

<screen><userinput>DRI_PRIME=1 glxinfo | grep -E "(OpenGL vendor|OpenGL renderer|OpenGL version)"</userinput></screen>

      will show OpenGL vendor, renderer and version for the discrete GPU.
    </para>

    <para>
      If the last command reports same OpenGL renderer with and without
      <envar>DRI_PRIME=1</envar>, you will need to check your installation.
    </para>

  </sect2>

  <sect2 role="configuration" id='xconfig'>
    <title>Setting up Xorg Devices</title>

    <para>
      For most hardware configurations, modern Xorg will automatically
      get the server configuration correct without any user intervention. There
      are, however, some cases where auto-configuration will be incorrect.
      Following are some example manual configuration items that may be of use
      in these instances.
    </para>

    <sect3 id="xinput">
      <title>Setting up X Input Devices</title>
      <para>
        For most input devices, no additional configuration will be
        necessary. This section is provided for informational purposes only.
      </para>

      <para>
        A sample default XKB setup could look like the following (executed as
        the <systemitem class="username">root</systemitem> user):
      </para>

<screen role="root"><userinput>cat &gt; /etc/X11/xorg.conf.d/xkb-defaults.conf &lt;&lt; "EOF"
<literal>Section "InputClass"
    Identifier "XKB Defaults"
    MatchIsKeyboard "yes"
    Option "XkbLayout" "fr"
    Option "XkbOptions" "terminate:ctrl_alt_bksp"
EndSection</literal>
EOF</userinput></screen>

      <para>
        The <quote>XkbLayout</quote> line is an example for a French (AZERTY)
        keyboard. Change it to your keyboard model. That line is not needed for
        a QWERTY (US) keyboard.
      </para>
    </sect3>

    <sect3 id="xdisplay">
      <title>Fine Tuning Display Settings</title>

      <para>
        Again, with modern Xorg, little or no additional configuration is
        necessary. If you should need extra options passed to your video driver,
        for instance, you could use something like the following (again,
        executed as the <systemitem class="username">root</systemitem> user):
      </para>

<screen role="root"><userinput>cat &gt; /etc/X11/xorg.conf.d/videocard-0.conf &lt;&lt; "EOF"
<literal>Section "Device"
    Identifier  "Videocard0"
    Driver      "radeon"
    VendorName  "Videocard vendor"
    BoardName   "ATI Radeon 7500"
    Option      "NoAccel" "true"
EndSection</literal>
EOF</userinput></screen>

      <para>
        Another common setup is having multiple server layouts for use in
        different environments. Though the server will automatically detect the
        presence of another monitor, it may get the order incorrect:
      </para>

<screen role="root"><userinput>cat &gt; /etc/X11/xorg.conf.d/server-layout.conf &lt;&lt; "EOF"
<literal>Section "ServerLayout"
    Identifier     "DefaultLayout"
    Screen      0  "Screen0" 0 0
    Screen      1  "Screen1" LeftOf "Screen0"
    Option         "Xinerama"
EndSection</literal>
EOF</userinput></screen>

    </sect3>
  </sect2>
</sect1>