docs/fbdev-dri.html

   1 <html>
   2
   3 <TITLE>Mesa fbdev/DRI Environment</TITLE>
   4
   5 <link rel="stylesheet" type="text/css" href="mesa.css"></head>
   6
   7 <BODY>
   8
   9 <center><H1>Mesa fbdev/DRI Drivers</H1></center>
  10
  11
  12 <H1>1. Introduction</H1>
  13
  14 <p>
  15 The fbdev/DRI sub-project within Mesa brings hardware accelerated OpenGL
  16 rendering to the Linux fbdev environment.
  17 The X Window System / XFree86 is not needed.
  18 </p>
  19
  20 <p>
  21 Basically, the <a href="http://dri.sf.net/">DRI</a> drivers for hardware
  22 accelerated OpenGL for XFree86 have been ported to fbdev so that X is
  23 not needed.
  24 This means fbdev/DRI works in full-screen mode only.
  25 </p>
  26
  27 <p>
  28 DRI driver writers may find this simplified environment easier to work in,
  29 compared to the full XFree86/DRI environment.
  30 </p>
  31
  32 <p>
  33 Much of the work for this project has been done by Jon Smirl and
  34 Keith Whitwell.
  35 </p>
  36
  37 <p>
  38 To use fbdev/DRI, you'll need a Linux 2.4 or 2.6 kernel.
  39 </p>
  40
  41 <h3>Background Info</h3>
  42
  43 <p>
  44 The Mesa-based DRI drivers used to be hosted in the DRI tree (which is
  45 basically a copy of the XFree86 tree).
  46 Since the Mesa-based DRI drivers are moreso "Mesa drivers" than "XFree86
  47 drivers" and the fact that with some work, the drivers could be used
  48 without X, the driver code was moved into the Mesa tree.
  49 </p>
  50
  51 <p>
  52 So now the DRI drivers can be compiled for two different environments:
  53 fbdev and XFree86.
  54 To build the drivers for XFree86, one has to download/build the DRI
  55 source tree.
  56 Eventually, we'd like to be able to build the drivers for XFree86 outside
  57 of the XFree86/DRI trees.
  58 </p>
  59
  60
  61
  62
  63 <h1>2. Compilation</h1>
  64
  65 <h2>2.1 Compiling the DRM modules</h2>
  66
  67 <p>
  68 First, you'll need the DRM (Direct Rendering Manager) kernel module sources.
  69 They're found in a module of the DRI CVS tree.
  70 To obtain the code do the following:
  71 </p>
  72 <pre>
  73    cvs -d:pserver:anonymous@pdx.freedesktop.org:/cvs/dri login
  74 </pre>
  75 <p>
  76 Press Enter/Return when prompted for a password.  Then,
  77 </p>
  78 <pre>
  79    cvs -d:pserver:anonymous@pdx.freedesktop.org:/cvs/dri co drm
  80 </pre>
  81
  82 <p>
  83 Compile the DRM kernel modules:
  84 </p>
  85 <pre>
  86   cd drm/linux
  87   make
  88 </pre>
  89
  90 <p>
  91 Note: you may need to be root in order to make a few symlinks.
  92 </p>
  93 <p>
  94 When compilation is done, you should have at least the following
  95 kernel modules:
  96 </p>
  97 <pre>
  98   gamma.o
  99   i810.o
 100   i830.o
 101   mach64.o
 102   mga.o
 103   r128.o
 104   radeon.o
 105   savage.o
 106   sis.o
 107   tdfx.o
 108   via.o
 109 </pre>
 110 <p>
 111 You'll probably want to copy/move them into your kernel module directory
 112 (for example: <code>/lib/modules/2.4.18-14/kernel/drivers/char/drm/</code>).
 113 </p>
 114
 115
 116
 117 <h2>2.2 Compiling the Mesa drivers</h2>
 118
 119 <p>
 120 Begin by editing the <code>Mesa/configs/default</code> file to set
 121 the <code>DRM_SOURCE_PATH</code> variable.
 122 Set it to the location where the DRM module sources are located.
 123 For example, if your current directory in step 2.1 was <code>/home/fred/</code>
 124 set DRM_SOURCE_PATH to <code>/home/fred/drm</code>
 125 </p>
 126
 127 <p>
 128 Next, assuming you're starting with a fresh Mesa CVS checkout,
 129 do the following:
 130 </p>
 131 <pre>
 132    make linux-solo
 133 </pre>
 134
 135 <p>
 136 If you previously built the source tree, run <code>make realclean</code>
 137 first to remove the old object files.
 138 </p>
 139
 140 <p>
 141 When this is finished, check the <code>Mesa/lib/</code> directory
 142 to verify that the following files were made:
 143 </p>
 144
 145 <ul>
 146 <li><code>libGL.so.1.2</code> - the client-side OpenGL library
 147     (and a few symlinks to it).
 148 <li><code>libGLU.so.1.1</code> - the GLU library (and a few symlinks to it).
 149 <li><code>libglut.so.3.7</code> - the GLUT library (and a few symlinks to it).
 150 <li><code>mga_dri.so</code> - DRI driver for Matrox G200/G400 cards.
 151 <li><code>r128_dri.so</code> - DRI driver for ATI Rage 128 cards.
 152 <li><code>r200_dri.so</code> - DRI driver for ATI R200 Radeon cards.
 153 <li><code>radeon_dri.so</code> - DRI driver for original ATI Radeon cards.
 154 <li><code>i810_dri.so</code> - DRI driver for Intel i810/i815 chips.
 155 <li><code>i830_dri.so</code> - DRI driver for Intel i830/i845 chips.
 156 <li><code>mga_dri.so</code> - DRI driver for Matrox G200/G400 cards.
 157 <li><code>sis_dri.so</code> - DRI driver for SIS cards.
 158 <li><code>tdfx_dri.so</code> - DRI driver for 3dfx Voodoo 3/4/5 cards.
 159 <li><code>gamma_dri.so</code> - DRI driver for 3Dlabs gamma cards.
 160 <li><code>fb_dri.so</code> - software-only fbdev driver.
 161 <li><code>miniglx.conf</code> - configuration file for the MiniGLX interface
 162 </ul>
 163
 164
 165 <h1>3. Using fbdev/DRI</h1>
 166
 167 <p>
 168 If XFree86 is currently running, exit/stop the X server so you're
 169 working from the console.
 170 </p>
 171
 172
 173 <h2>3.1 Load Kernel Modules</h2>
 174
 175 <p>
 176 You'll need to load the kernel modules specific to your graphics hardware.
 177 Typically, this consists of the agpgart module, an fbdev driver module
 178 and the DRM kernel module (from step 2.1).
 179 </p>
 180
 181
 182 <p>
 183 If you have ATI Radeon/R200 hardware, run as root:
 184 </p>
 185 <pre>
 186    modprobe agpgart            # the AGP GART module
 187    modprobe radeonfb           # the Radeon fbdev driver
 188    modprobe radeon             # the Radeon DRI kernel module
 189 </pre>
 190
 191 <p>
 192 If you have ATI Rage 128 hardware, run as root:
 193 </p>
 194 <pre>
 195    modprobe agpgart            # the AGP GART module
 196    modprobe aty128fb           # the Rage 128 fbdev driver
 197    modprobe r128               # the Rage 128 DRI kernel module
 198 </pre>
 199
 200 <p>
 201 If you have Matrox G200/G400 hardware, run as root:
 202 </p>
 203 <pre>
 204    modprobe agpgart            # the AGP GART module
 205    modprobe mgafb              # the Matrox fbdev driver
 206    modprobe mga                # the Matrox DRI kernel module
 207 </pre>
 208
 209 <p>
 210 Then run <code>lsmod</code> to be sure the modules are loaded.
 211 For a Radeon card, you should see something like this:
 212 </p>
 213 <pre>
 214 Module                  Size  Used by    Not tainted
 215 radeon                110308   0  (unused)
 216 radeonfb               21900   0  (unused)
 217 agpgart                43072   1
 218 </pre>
 219
 220
 221
 222 <h2>3.2 Configuration File</h2>
 223
 224 <p>
 225 The <code>Mesa/lib/miniglx.conf</code> file should be installed
 226 in <code>/etc/</code>.
 227 </p>
 228
 229 <p>
 230 Edit <code>/etc/miniglx.conf</code> to be sure it's set up correctly
 231 for your hardware.
 232 Comments in the file explain the options.
 233 </p>
 234
 235
 236 <h2>3.3 Running fbdev/DRI Programs</h2>
 237
 238 <p>
 239 Make sure your LD_LIBRARY_PATH environment variable is set to the
 240 <code>Mesa/lib/</code> directory.
 241 </p>
 242
 243 <p>
 244 Change to the <code>Mesa/progs/miniglx/</code> directory and
 245 start the sample_server program in the background:
 246 </p>
 247 <pre>
 248    ./sample_server &
 249 </pre>
 250
 251 <p>
 252 Then try running the <code>miniglxtest</code> program:
 253 </p>
 254 <pre>
 255    ./miniglxtest
 256 </pre>
 257 <p>
 258 You should see a rotating quadrilateral which changes color as it rotates.
 259 It will exit automatically after a bit.
 260 </p>
 261
 262 <p>
 263 If you run other tests in the miniglx/ directory, you may want to run
 264 them from a remote shell so that you can stop them with ctrl-C.
 265 </p>
 266
 267
 268
 269 <h1>4.0 Troubleshooting</h1>
 270
 271 <p>
 272 If you try to run miniglxtest and get the following:
 273 </p>
 274 <pre>
 275    [miniglx] failed to probe chipset
 276    connect: Connection refused
 277    server connection lost
 278 </pre>
 279 <p>
 280 It means that the sample_server process is not running.
 281 </p>
 282
 283
 284
 285
 286 <h1>5.0 Programming Information</h1>
 287
 288 <p>
 289 The full OpenGL API is available with fbdev/DRI.
 290 </p>
 291
 292 <p>
 293 OpenGL/Mesa is interfaced to fbdev via the <a href="MiniGLX.html">MiniGLX</a>
 294 interface.
 295 MiniGLX is a subset of Xlib and GLX API functions which provides just
 296 enough functionality to setup OpenGL rendering and respond to simple
 297 input events.
 298 </p>
 299
 300 <p>
 301 Since MiniGLX is a subset of the usual Xlib and GLX APIs, programs written
 302 to the MiniGLX API can also be run on full Xlib/GLX implementations.
 303 This allows some degree of flexibility for software development and testing.
 304 </p>
 305
 306 <p>
 307 However, the MiniGLX API is not binary-compatible with full Xlib/GLX.
 308 Some of the structures are different and some macros/functions work
 309 differently.
 310 See the <code>GL/miniglx.h</code> header file for details.
 311 </p>
 312
 313
 314 </body>
 315 </html>