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