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

<?xml version="1.0" encoding="ISO-8859-1"?>
<!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>
    <othername>$LastChangedBy$</othername>
    <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>

    <para>To test the <application>Xorg</application> installation, issue
    <userinput>startx</userinput>.  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>

    <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>/var/log/Xorg.0.log</filename> 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.ati.com/">ATI</ulink>.
      </para>
    </note>

    <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.
    </para>
<!--
    <para>
      To see if hardware acceleration is available for your driver, look in
      <filename>/var/log/Xorg.0.log</filename> for statements like:
    </para>

<screen><literal>(II) intel(0): direct rendering: DRI2 Enabled</literal></screen>
-->
    <para>
      If your driver is supported, add any users that might use X to that group:
    </para>

<screen role="root"><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 | egrep "(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 ot 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="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
      with an optional patch applied.
    </para>

    <para>
      <application>Xorg Server</application> should load both GPU drivers automaticaly.
      In order to run a GLX application on a discrete GPU, you will need to export
      the <envar>DRI_PRIME=1</envar> environment variable. For example,

<screen><userinput>DRI_PRIME=1 glxinfo | egrep "(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><userinput role="username">cat &gt; /etc/X11/xorg.conf.d/xkb-defaults.conf &lt;&lt; "EOF"
Section "InputClass"
    Identifier "XKB Defaults"
    MatchIsKeyboard "yes"
    Option "XkbOptions" "terminate:ctrl_alt_bksp"
EndSection
EOF</userinput></screen>

  </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><userinput role="root">cat &gt; /etc/X11/xorg.conf.d/videocard-0.conf &lt;&lt; "EOF"
Section "Device"
    Identifier  "Videocard0"
    Driver      "radeon"
    VendorName  "Videocard vendor"
    BoardName   "ATI Radeon 7500"
    Option      "NoAccel" "true"
EndSection
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><userinput role="root">cat &gt; /etc/X11/xorg.conf.d/server-layout.conf &lt;&lt; "EOF"
Section "ServerLayout"
    Identifier     "DefaultLayout"
    Screen      0  "Screen0" 0 0
    Screen      1  "Screen1" LeftOf "Screen0"
    Option         "Xinerama"
EndSection
EOF</userinput></screen>

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