Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / mesa3d / 4a54ace195b3775ba5408e6f71464d924ede0237 / . / docs / fbdev-dri.html
blob: 06277f5655f686e2f151cd103007bcdf90475231 [file] [log] [blame]
Brian Paul4a54ace2004-05-20 22:27:59 +0000[diff] [blame^]1<html>
Brian Paul56e9efa2003-09-03 23:04:02 +0000[diff] [blame]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>
13The fbdev/DRI sub-project within Mesa brings hardware accelerated OpenGL
14rendering to the Linux fbdev environment.
15The X Window System / XFree86 is not needed.
16</p>
17
18<p>
19Basically, the <a href="http://dri.sf.net/">DRI</a> drivers for hardware
20accelerated OpenGL for XFree86 have been ported to fbdev so that X is
21not needed.
22This means fbdev/DRI works in full-screen mode only.
23</p>
24
25<p>
26DRI driver writers may find this simplified environment easier to work in,
27compared to the full XFree86/DRI environment.
28</p>
29
30<p>
31Much of the work for this project has been done by Jon Smirl and
32Keith Whitwell.
33</p>
34
35<p>
36To use fbdev/DRI, you'll need a Linux 2.4 or 2.6 kernel.
37</p>
38
Brian Paul4a54ace2004-05-20 22:27:59 +0000[diff] [blame^]39<h3>Background Info</h3>
40
Brian Paul56e9efa2003-09-03 23:04:02 +0000[diff] [blame]41<p>
Brian Paul4a54ace2004-05-20 22:27:59 +0000[diff] [blame^]42The Mesa-based DRI drivers used to be hosted in the DRI tree (which is
43basically a copy of the XFree86 tree).
44Since the Mesa-based DRI drivers are moreso "Mesa drivers" than "XFree86
45drivers" and the fact that with some work, the drivers could be used
46without X, the driver code was moved into the Mesa tree.
Brian Paul56e9efa2003-09-03 23:04:02 +0000[diff] [blame]47</p>
48
Brian Paul4a54ace2004-05-20 22:27:59 +0000[diff] [blame^]49<p>
50So now the DRI drivers can be compiled for two different environments:
51fbdev and XFree86.
52To build the drivers for XFree86, one has to download/build the DRI
53source tree.
54Eventually, we'd like to be able to build the drivers for XFree86 outside
55of the XFree86/DRI trees.
56</p>
57
58
59
Brian Paul56e9efa2003-09-03 23:04:02 +0000[diff] [blame]60
61<h1>2. Compilation</h1>
62
Brian Paul4a54ace2004-05-20 22:27:59 +0000[diff] [blame^]63<h2>2.1 Compiling the DRM modules</h2>
64
Brian Paul56e9efa2003-09-03 23:04:02 +0000[diff] [blame]65<p>
Brian Paul4a54ace2004-05-20 22:27:59 +0000[diff] [blame^]66First, you'll need the DRM (Direct Rendering Manager) kernel module sources.
67They're found in a module of the DRI CVS tree.
68To 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>
74Press 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>
81Compile the DRM kernel modules:
82</p>
83<pre>
84 cd drm/linux
85 make
86</pre>
87
88<p>
89Note: you may need to be root in order to make a few symlinks.
90</p>
91<p>
92When compilation is done, you should have at least the following
93kernel 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>
109You'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>
118Begin by editing the <code>Mesa/configs/default</code> file to set
119the <code>DRM_SOURCE_PATH</code> variable.
120Set it to the location where the DRM module sources are located.
121For example, if your current directory in step 2.1 was <code>/home/fred/</code>
122set DRM_SOURCE_PATH to <code>/home/fred/drm</code>
123</p>
124
125<p>
126Next, assuming you're starting with a fresh Mesa CVS checkout,
127do the following:
Brian Paul56e9efa2003-09-03 23:04:02 +0000[diff] [blame]128</p>
129<pre>
Brian Paul56e9efa2003-09-03 23:04:02 +0000[diff] [blame]130 make linux-solo
131</pre>
132
133<p>
Brian Paulf4b909b2004-04-18 20:17:14 +0000[diff] [blame]134If you previously built the source tree, run <code>make realclean</code>
135first to remove the old object files.
136</p>
137
138<p>
Brian Paul4a54ace2004-05-20 22:27:59 +0000[diff] [blame^]139When this is finished, check the <code>Mesa/lib/</code> directory
Brian Paul56e9efa2003-09-03 23:04:02 +0000[diff] [blame]140to 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.
Brian Pauld7a2a7f2003-12-12 15:44:11 +0000[diff] [blame]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.
Brian Paul56e9efa2003-09-03 23:04:02 +0000[diff] [blame]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>
166If XFree86 is currently running, exit/stop the X server so you're
167working from the console.
168</p>
169
170
Brian Paul4a54ace2004-05-20 22:27:59 +0000[diff] [blame^]171<h2>3.1 Load Kernel Modules</h2>
Brian Paul56e9efa2003-09-03 23:04:02 +0000[diff] [blame]172
173<p>
Brian Paul4a54ace2004-05-20 22:27:59 +0000[diff] [blame^]174You'll need to load the kernel modules specific to your graphics hardware.
175Typically, this consists of the agpgart module, an fbdev driver module
176and the DRM kernel module (from step 2.1).
Brian Paul56e9efa2003-09-03 23:04:02 +0000[diff] [blame]177</p>
178
179
180<p>
181If 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>
190If 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>
199If 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>
208Then run <code>lsmod</code> to be sure the modules are loaded.
209For a Radeon card, you should see something like this:
210</p>
211<pre>
212Module Size Used by Not tainted
213radeon 110308 0 (unused)
214radeonfb 21900 0 (unused)
215agpgart 43072 1
216</pre>
217
Brian Paul70dacab2004-02-13 18:29:42 +0000[diff] [blame]218
Brian Paul56e9efa2003-09-03 23:04:02 +0000[diff] [blame]219
220<h2>3.2 Configuration File</h2>
221
222<p>
Brian Paulf4b909b2004-04-18 20:17:14 +0000[diff] [blame]223The <code>Mesa/lib/miniglx.conf</code> file should be installed
Brian Paul56e9efa2003-09-03 23:04:02 +0000[diff] [blame]224in <code>/etc/</code>.
225</p>
226
227<p>
228Edit <code>/etc/miniglx.conf</code> to be sure it's set up correctly
229for your hardware.
230Comments in the file explain the options.
231</p>
232
233
234<h2>3.3 Running fbdev/DRI Programs</h2>
235
236<p>
237Make sure your LD_LIBRARY_PATH environment variable is set to the
Brian Paulf4b909b2004-04-18 20:17:14 +0000[diff] [blame]238<code>Mesa/lib/</code> directory.
Brian Paul56e9efa2003-09-03 23:04:02 +0000[diff] [blame]239</p>
240
241<p>
Brian Paulf4b909b2004-04-18 20:17:14 +0000[diff] [blame]242Change to the <code>Mesa/progs/miniglx/</code> directory and
Brian Paul56e9efa2003-09-03 23:04:02 +0000[diff] [blame]243start the sample_server program in the background:
244</p>
245<pre>
246 ./sample_server &
247</pre>
248
249<p>
250Then try running the <code>miniglxtest</code> program:
251</p>
252<pre>
253 ./miniglxtest
254</pre>
255<p>
256You should see a rotating quadrilateral which changes color as it rotates.
257It will exit automatically after a bit.
258</p>
259
260<p>
261If you run other tests in the miniglx/ directory, you may want to run
262them 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>
270If 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>
278It 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>
287The full OpenGL API is available with fbdev/DRI.
288</p>
289
290<p>
291OpenGL/Mesa is interfaced to fbdev via the <a href="MiniGLX.html">MiniGLX</a>
292interface.
293MiniGLX is a subset of Xlib and GLX API functions which provides just
294enough functionality to setup OpenGL rendering and respond to simple
295input events.
296</p>
297
298<p>
299Since MiniGLX is a subset of the usual Xlib and GLX APIs, programs written
300to the MiniGLX API can also be run on full Xlib/GLX implementations.
301This allows some degree of flexibility for software development and testing.
302</p>
303
Brian Paule0823482003-09-03 23:10:31 +0000[diff] [blame]304<p>
305However, the MiniGLX API is not binary-compatible with full Xlib/GLX.
306Some of the structures are different and some macros/functions work
307differently.
308See the <code>GL/miniglx.h</code> header file for details.
309</p>
Brian Paul56e9efa2003-09-03 23:04:02 +0000[diff] [blame]310
311
312</body>
313</html>