docs/fbdev-dri.html

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