docs/fbdev-dri.html - fp2-dev/platform/external/mesa3d - Gitiles

 <html>

 <TITLE>Mesa fbdev/DRI Environment</TITLE>

 <link rel="stylesheet" type="text/css" href="mesa.css"></head>

 <BODY>

 <center><H1>Mesa fbdev/DRI Drivers</H1></center>


 <H1>1. Introduction</H1>

 <p>
 The fbdev/DRI sub-project within Mesa brings hardware accelerated OpenGL
 rendering to the Linux fbdev environment.
 The X Window System / XFree86 is not needed.
 </p>

 <p>
 Basically, the <a href="http://dri.sf.net/">DRI</a> drivers for hardware
 accelerated OpenGL for XFree86 have been ported to fbdev so that X is
 not needed.
 This means fbdev/DRI works in full-screen mode only.
 </p>

 <p>
 DRI driver writers may find this simplified environment easier to work in,
 compared to the full XFree86/DRI environment.
 </p>

 <p>
 Much of the work for this project has been done by Jon Smirl and
 Keith Whitwell.
 </p>

 <p>
 To use fbdev/DRI, you'll need a Linux 2.4 or 2.6 kernel.
 </p>

 <h3>Background Info</h3>

 <p>
 The Mesa-based DRI drivers used to be hosted in the DRI tree (which is
 basically a copy of the XFree86 tree).
 Since the Mesa-based DRI drivers are moreso "Mesa drivers" than "XFree86
 drivers" and the fact that with some work, the drivers could be used
 without X, the driver code was moved into the Mesa tree.
 </p>

 <p>
 So now the DRI drivers can be compiled for two different environments:
 fbdev and XFree86.
 To build the drivers for XFree86, one has to download/build the DRI
 source tree.
 Eventually, we'd like to be able to build the drivers for XFree86 outside
 of the XFree86/DRI trees.
 </p>


 <h1>2. Compilation</h1>

 <h2>2.1 Compiling the DRM modules</h2>

 <p>
 First, you'll need the DRM (Direct Rendering Manager) kernel module sources.
 They're found in a module of the DRI CVS tree.
 To obtain the code do the following:
 </p>
 <pre>
    cvs -d:pserver:anonymous@pdx.freedesktop.org:/cvs/dri login
 </pre>
 <p>
 Press Enter/Return when prompted for a password.  Then,
 </p>
 <pre>
    cvs -d:pserver:anonymous@pdx.freedesktop.org:/cvs/dri co drm
 </pre>

 <p>
 Compile the DRM kernel modules:
 </p>
 <pre>
   cd drm/linux
   make
 </pre>

 <p>
 Note: you may need to be root in order to make a few symlinks.
 </p>
 <p>
 When compilation is done, you should have at least the following
 kernel modules:
 </p>
 <pre>
   gamma.o
   i810.o
   i830.o
   mach64.o
   mga.o
   r128.o
   radeon.o
   savage.o
   sis.o
   tdfx.o
   via.o
 </pre>
 <p>
 You'll probably want to copy/move them into your kernel module directory
 (for example: <code>/lib/modules/2.4.18-14/kernel/drivers/char/drm/</code>).
 </p>


 <h2>2.2 Compiling the Mesa drivers</h2>

 <p>
 Begin by editing the <code>Mesa/configs/default</code> file to set
 the <code>DRM_SOURCE_PATH</code> variable.
 Set it to the location where the DRM module sources are located.
 For example, if your current directory in step 2.1 was <code>/home/fred/</code>
 set DRM_SOURCE_PATH to <code>/home/fred/drm</code>
 </p>

 <p>
 Next, assuming you're starting with a fresh Mesa CVS checkout,
 do the following:
 </p>
 <pre>
    make linux-solo
 </pre>

 <p>
 If you previously built the source tree, run <code>make realclean</code>
 first to remove the old object files.
 </p>

 <p>
 When this is finished, check the <code>Mesa/lib/</code> directory
 to verify that the following files were made:
 </p>

 <ul>
 <li><code>libGL.so.1.2</code> - the client-side OpenGL library
     (and a few symlinks to it).
 <li><code>libGLU.so.1.1</code> - the GLU library (and a few symlinks to it).
 <li><code>libglut.so.3.7</code> - the GLUT library (and a few symlinks to it).
 <li><code>mga_dri.so</code> - DRI driver for Matrox G200/G400 cards.
 <li><code>r128_dri.so</code> - DRI driver for ATI Rage 128 cards.
 <li><code>r200_dri.so</code> - DRI driver for ATI R200 Radeon cards.
 <li><code>radeon_dri.so</code> - DRI driver for original ATI Radeon cards.
 <li><code>i810_dri.so</code> - DRI driver for Intel i810/i815 chips.
 <li><code>i830_dri.so</code> - DRI driver for Intel i830/i845 chips.
 <li><code>mga_dri.so</code> - DRI driver for Matrox G200/G400 cards.
 <li><code>sis_dri.so</code> - DRI driver for SIS cards.
 <li><code>tdfx_dri.so</code> - DRI driver for 3dfx Voodoo 3/4/5 cards.
 <li><code>gamma_dri.so</code> - DRI driver for 3Dlabs gamma cards.
 <li><code>fb_dri.so</code> - software-only fbdev driver.
 <li><code>miniglx.conf</code> - configuration file for the MiniGLX interface
 </ul>


 <h1>3. Using fbdev/DRI</h1>

 <p>
 If XFree86 is currently running, exit/stop the X server so you're
 working from the console.
 </p>


 <h2>3.1 Load Kernel Modules</h2>

 <p>
 You'll need to load the kernel modules specific to your graphics hardware.
 Typically, this consists of the agpgart module, an fbdev driver module
 and the DRM kernel module (from step 2.1).
 </p>


 <p>
 If you have ATI Radeon/R200 hardware, run as root:
 </p>
 <pre>
    modprobe agpgart            # the AGP GART module
    modprobe radeonfb           # the Radeon fbdev driver
    modprobe radeon             # the Radeon DRI kernel module
 </pre>

 <p>
 If you have ATI Rage 128 hardware, run as root:
 </p>
 <pre>
    modprobe agpgart            # the AGP GART module
    modprobe aty128fb           # the Rage 128 fbdev driver
    modprobe r128               # the Rage 128 DRI kernel module
 </pre>

 <p>
 If you have Matrox G200/G400 hardware, run as root:
 </p>
 <pre>
    modprobe agpgart            # the AGP GART module
    modprobe mgafb              # the Matrox fbdev driver
    modprobe mga                # the Matrox DRI kernel module
 </pre>

 <p>
 Then run <code>lsmod</code> to be sure the modules are loaded.
 For a Radeon card, you should see something like this:
 </p>
 <pre>
 Module                  Size  Used by    Not tainted
 radeon                110308   0  (unused)
 radeonfb               21900   0  (unused)
 agpgart                43072   1
 </pre>


 <h2>3.2 Configuration File</h2>

 <p>
 The <code>Mesa/lib/miniglx.conf</code> file should be installed
 in <code>/etc/</code>.
 </p>

 <p>
 Edit <code>/etc/miniglx.conf</code> to be sure it's set up correctly
 for your hardware.
 Comments in the file explain the options.
 </p>


 <h2>3.3 Running fbdev/DRI Programs</h2>

 <p>
 Make sure your LD_LIBRARY_PATH environment variable is set to the
 <code>Mesa/lib/</code> directory.
 </p>

 <p>
 Change to the <code>Mesa/progs/miniglx/</code> directory and
 start the sample_server program in the background:
 </p>
 <pre>
    ./sample_server &
 </pre>

 <p>
 Then try running the <code>miniglxtest</code> program:
 </p>
 <pre>
    ./miniglxtest
 </pre>
 <p>
 You should see a rotating quadrilateral which changes color as it rotates.
 It will exit automatically after a bit.
 </p>

 <p>
 If you run other tests in the miniglx/ directory, you may want to run
 them from a remote shell so that you can stop them with ctrl-C.
 </p>


 <h1>4.0 Troubleshooting</h1>

 <p>
 If you try to run miniglxtest and get the following:
 </p>
 <pre>
    [miniglx] failed to probe chipset
    connect: Connection refused
    server connection lost
 </pre>
 <p>
 It means that the sample_server process is not running.
 </p>


 <h1>5.0 Programming Information</h1>

 <p>
 The full OpenGL API is available with fbdev/DRI.
 </p>

 <p>
 OpenGL/Mesa is interfaced to fbdev via the <a href="MiniGLX.html">MiniGLX</a>
 interface.
 MiniGLX is a subset of Xlib and GLX API functions which provides just
 enough functionality to setup OpenGL rendering and respond to simple
 input events.
 </p>

 <p>
 Since MiniGLX is a subset of the usual Xlib and GLX APIs, programs written
 to the MiniGLX API can also be run on full Xlib/GLX implementations.
 This allows some degree of flexibility for software development and testing.
 </p>

 <p>
 However, the MiniGLX API is not binary-compatible with full Xlib/GLX.
 Some of the structures are different and some macros/functions work
 differently.
 See the <code>GL/miniglx.h</code> header file for details.
 </p>


 </body>
 </html>
	<html>

	<TITLE>Mesa fbdev/DRI Environment</TITLE>

	<link rel="stylesheet" type="text/css" href="mesa.css"></head>

	<BODY>

	<center><H1>Mesa fbdev/DRI Drivers</H1></center>


	<H1>1. Introduction</H1>

	<p>
	The fbdev/DRI sub-project within Mesa brings hardware accelerated OpenGL
	rendering to the Linux fbdev environment.
	The X Window System / XFree86 is not needed.
	</p>

	<p>
	Basically, the <a href="http://dri.sf.net/">DRI</a> drivers for hardware
	accelerated OpenGL for XFree86 have been ported to fbdev so that X is
	not needed.
	This means fbdev/DRI works in full-screen mode only.
	</p>

	<p>
	DRI driver writers may find this simplified environment easier to work in,
	compared to the full XFree86/DRI environment.
	</p>

	<p>
	Much of the work for this project has been done by Jon Smirl and
	Keith Whitwell.
	</p>

	<p>
	To use fbdev/DRI, you'll need a Linux 2.4 or 2.6 kernel.
	</p>

	<h3>Background Info</h3>

	<p>
	The Mesa-based DRI drivers used to be hosted in the DRI tree (which is
	basically a copy of the XFree86 tree).
	Since the Mesa-based DRI drivers are moreso "Mesa drivers" than "XFree86
	drivers" and the fact that with some work, the drivers could be used
	without X, the driver code was moved into the Mesa tree.
	</p>

	<p>
	So now the DRI drivers can be compiled for two different environments:
	fbdev and XFree86.
	To build the drivers for XFree86, one has to download/build the DRI
	source tree.
	Eventually, we'd like to be able to build the drivers for XFree86 outside
	of the XFree86/DRI trees.
	</p>




	<h1>2. Compilation</h1>

	<h2>2.1 Compiling the DRM modules</h2>

	<p>
	First, you'll need the DRM (Direct Rendering Manager) kernel module sources.
	They're found in a module of the DRI CVS tree.
	To obtain the code do the following:
	</p>
	<pre>
	cvs -d:pserver:anonymous@pdx.freedesktop.org:/cvs/dri login
	</pre>
	<p>
	Press Enter/Return when prompted for a password. Then,
	</p>
	<pre>
	cvs -d:pserver:anonymous@pdx.freedesktop.org:/cvs/dri co drm
	</pre>

	<p>
	Compile the DRM kernel modules:
	</p>
	<pre>
	cd drm/linux
	make
	</pre>

	<p>
	Note: you may need to be root in order to make a few symlinks.
	</p>
	<p>
	When compilation is done, you should have at least the following
	kernel modules:
	</p>
	<pre>
	gamma.o
	i810.o
	i830.o
	mach64.o
	mga.o
	r128.o
	radeon.o
	savage.o
	sis.o
	tdfx.o
	via.o
	</pre>
	<p>
	You'll probably want to copy/move them into your kernel module directory
	(for example: <code>/lib/modules/2.4.18-14/kernel/drivers/char/drm/</code>).
	</p>



	<h2>2.2 Compiling the Mesa drivers</h2>

	<p>
	Begin by editing the <code>Mesa/configs/default</code> file to set
	the <code>DRM_SOURCE_PATH</code> variable.
	Set it to the location where the DRM module sources are located.
	For example, if your current directory in step 2.1 was <code>/home/fred/</code>
	set DRM_SOURCE_PATH to <code>/home/fred/drm</code>
	</p>

	<p>
	Next, assuming you're starting with a fresh Mesa CVS checkout,
	do the following:
	</p>
	<pre>
	make linux-solo
	</pre>

	<p>
	If you previously built the source tree, run <code>make realclean</code>
	first to remove the old object files.
	</p>

	<p>
	When this is finished, check the <code>Mesa/lib/</code> directory
	to verify that the following files were made:
	</p>

	<ul>
	<li><code>libGL.so.1.2</code> - the client-side OpenGL library
	(and a few symlinks to it).
	<li><code>libGLU.so.1.1</code> - the GLU library (and a few symlinks to it).
	<li><code>libglut.so.3.7</code> - the GLUT library (and a few symlinks to it).
	<li><code>mga_dri.so</code> - DRI driver for Matrox G200/G400 cards.
	<li><code>r128_dri.so</code> - DRI driver for ATI Rage 128 cards.
	<li><code>r200_dri.so</code> - DRI driver for ATI R200 Radeon cards.
	<li><code>radeon_dri.so</code> - DRI driver for original ATI Radeon cards.
	<li><code>i810_dri.so</code> - DRI driver for Intel i810/i815 chips.
	<li><code>i830_dri.so</code> - DRI driver for Intel i830/i845 chips.
	<li><code>mga_dri.so</code> - DRI driver for Matrox G200/G400 cards.
	<li><code>sis_dri.so</code> - DRI driver for SIS cards.
	<li><code>tdfx_dri.so</code> - DRI driver for 3dfx Voodoo 3/4/5 cards.
	<li><code>gamma_dri.so</code> - DRI driver for 3Dlabs gamma cards.
	<li><code>fb_dri.so</code> - software-only fbdev driver.
	<li><code>miniglx.conf</code> - configuration file for the MiniGLX interface
	</ul>


	<h1>3. Using fbdev/DRI</h1>

	<p>
	If XFree86 is currently running, exit/stop the X server so you're
	working from the console.
	</p>


	<h2>3.1 Load Kernel Modules</h2>

	<p>
	You'll need to load the kernel modules specific to your graphics hardware.
	Typically, this consists of the agpgart module, an fbdev driver module
	and the DRM kernel module (from step 2.1).
	</p>


	<p>
	If you have ATI Radeon/R200 hardware, run as root:
	</p>
	<pre>
	modprobe agpgart # the AGP GART module
	modprobe radeonfb # the Radeon fbdev driver
	modprobe radeon # the Radeon DRI kernel module
	</pre>

	<p>
	If you have ATI Rage 128 hardware, run as root:
	</p>
	<pre>
	modprobe agpgart # the AGP GART module
	modprobe aty128fb # the Rage 128 fbdev driver
	modprobe r128 # the Rage 128 DRI kernel module
	</pre>

	<p>
	If you have Matrox G200/G400 hardware, run as root:
	</p>
	<pre>
	modprobe agpgart # the AGP GART module
	modprobe mgafb # the Matrox fbdev driver
	modprobe mga # the Matrox DRI kernel module
	</pre>

	<p>
	Then run <code>lsmod</code> to be sure the modules are loaded.
	For a Radeon card, you should see something like this:
	</p>
	<pre>
	Module Size Used by Not tainted
	radeon 110308 0 (unused)
	radeonfb 21900 0 (unused)
	agpgart 43072 1
	</pre>



	<h2>3.2 Configuration File</h2>

	<p>
	The <code>Mesa/lib/miniglx.conf</code> file should be installed
	in <code>/etc/</code>.
	</p>

	<p>
	Edit <code>/etc/miniglx.conf</code> to be sure it's set up correctly
	for your hardware.
	Comments in the file explain the options.
	</p>


	<h2>3.3 Running fbdev/DRI Programs</h2>

	<p>
	Make sure your LD_LIBRARY_PATH environment variable is set to the
	<code>Mesa/lib/</code> directory.
	</p>

	<p>
	Change to the <code>Mesa/progs/miniglx/</code> directory and
	start the sample_server program in the background:
	</p>
	<pre>
	./sample_server &
	</pre>

	<p>
	Then try running the <code>miniglxtest</code> program:
	</p>
	<pre>
	./miniglxtest
	</pre>
	<p>
	You should see a rotating quadrilateral which changes color as it rotates.
	It will exit automatically after a bit.
	</p>

	<p>
	If you run other tests in the miniglx/ directory, you may want to run
	them from a remote shell so that you can stop them with ctrl-C.
	</p>



	<h1>4.0 Troubleshooting</h1>

	<p>
	If you try to run miniglxtest and get the following:
	</p>
	<pre>
	[miniglx] failed to probe chipset
	connect: Connection refused
	server connection lost
	</pre>
	<p>
	It means that the sample_server process is not running.
	</p>




	<h1>5.0 Programming Information</h1>

	<p>
	The full OpenGL API is available with fbdev/DRI.
	</p>

	<p>
	OpenGL/Mesa is interfaced to fbdev via the <a href="MiniGLX.html">MiniGLX</a>
	interface.
	MiniGLX is a subset of Xlib and GLX API functions which provides just
	enough functionality to setup OpenGL rendering and respond to simple
	input events.
	</p>

	<p>
	Since MiniGLX is a subset of the usual Xlib and GLX APIs, programs written
	to the MiniGLX API can also be run on full Xlib/GLX implementations.
	This allows some degree of flexibility for software development and testing.
	</p>

	<p>
	However, the MiniGLX API is not binary-compatible with full Xlib/GLX.
	Some of the structures are different and some macros/functions work
	differently.
	See the <code>GL/miniglx.h</code> header file for details.
	</p>


	</body>
	</html>