2. Getting Started

2.1. How do I get started with development?

To get started with development you have to first understand the DRI and XFree86 architecture. You can start by reading the developer documents in the documentation section of this website.

Then you can continue by checking out the DRI CVS tree. Poke around the driver source code to find out some more about the inner workings of the DRI. There also are some text documents within the XFree86 source tree that contain useful information.

Once you feel that you have sufficient understanding of the DRI to begin coding you can start by submitting a patch. You have to submit at least one patch to get write access to our CVS. Have a look at the Sourceforge bug tracker for open issues. That is a good place to find an issue that you can fix by submitting a patch.

After you have submitted your patch you can start working on a more concrete project. Have a look at the status page or read the newsgroups for projects that need to be worked on.

Of course you don't have to submit a patch before you can work on a project. But since you wont be able to check in your work until you submit a patch it is very desirable to submit a patch first. You do want people to test your work, right?

Also, don't be shy about asking questions on the dri-devel newsgroup. The main purpose of the newsgroup is the discussion of development issues. So, feel free to ask questions.

2.2. How do I submit a patch?

There are two ways you can submit a patch.

Preferably you will submit the patch through our Sourceforge project page. That way we can easily find your user id to add you to the project as a developer and give you CVS access.

You can also submit a patch by posting it to the dri-devel newsgroup as an attachment to a message.

In any case, make sure you explain clearly what your patch is for.

2.3. How is constituted a DRI driver?

All DRI drivers are made up of 3 parts:

2.4. Do I need to understand the X11 in order to help?

 

I do not understand the X11 codebase. Not one bit. Never even looked at it, probably never intend to. Do I need to understand this in order to work on the DRI/Mesa drivers? Nope. At a bare minimum, I'd need to know how the Mesa Device Driver (DD) interface works, and have a basic understanding of OpenGL. This would allow me to work on the client-side driver code (xc/lib/GL/mesa/src/drv/*). Having more knowledge about the internals of Mesa certainly helps, and if you're keen you can check out the chipset specific stuff in the DRM (which is fairly closely tied to the client-side driver code mentioned above, and mainly deals with DMA transfers etc). No one ever said it would be easy to pick up, but it's not like you have to have a working knowledge of the entire X server to work on the 3D drivers…

 
--Gareth Hughes 

2.5. I want to start the development of a new driver. Which one should I took as template?

The tdfx driver is rather old, and was the place a lot of experimentation was done. It isn`t an example of a good driver.

To start out I`d concentrate on the i810. The design of that driver is very clean, and makes a good base to build upon. (Given more time and resources I`d rewrite the tdfx driver to act more like the i810).

There are a few possibilities you have to consider:

The security issue that is seen most often is being able to write to PCI memory. Cards might do this via a 2D blit mode which allows blitting to/from main memory, or perhaps by a special DMA instruction which writes a counter dword into PCI space. These are very useful operations, but can be exploited to write to, eg, the bit of memory which holds a process` UID number.

Most hardware seems to have been designed for consumer versions of Windows, which don`t really have a security model.

So, you need to verify there is no mechanism to write to PCI space (in any way or form).

If there is no DMA interface — as long as the card is secure — that is probably going to simplify the task of writing the driver, as there will be only a tiny kernel component. The tdfx kernel driver should be the basis for your kernel part — there should be very few changes. You can use the basic structure of the i810 3D driver for state management, etc, but you will want to emit state directly via PIO instead of via DMA. You will need to look at how the tdfx driver emits cliprects in the triangle routines — you`ll need to do something similar.

2.6. What's the DRI history?

 

This is mostly a history of the DRI [1]. If you're interested, print it out and snuggle up by the fire…

At SigGraph of '98 (August 1998) there was a Linux 3D BOF. Brian, Daryll and others gave good talks at this meeting. I had a short talk near the end where I basically asked for any community members interested in developing a direct rendering infrastructure to contact me. From this, I got two responses with no follow up.

So, Kevin and I sat down and wrote the high level design document, which outlined many alternatives and recommended a single path for implementing direct rendering. This document was released less than two months after my siggraph plea for involvement. We posted the following e-mail to the mailing list in September of 1998:

Subject: Direct Rendering for 3D
From: Jens Owen (jens@precisioninsight.com)
Date: Sun, 20 Sep 1998 12:40:07 -0600 

We have released our high-level design document which describes a
direct rendering architecture for 3D applications. This document
can be found at: 

http://www.precisioninsight.com/dr/dr.html 

Our intention is to create a sample implementation of the 3D 
infrastructure using Mesa and XFree86 with full source available
under an XFree86-style license. 

We are sending this e-mail to XFree86, Mesa, and kernel developers
in an effort to receive feedback on the high level design. We
would like to receive comments back by 12 Oct 98 as we plan to
start on the low level design at that point. 

Regards, 
Jens Owen and Kevin E. Martin
			

This e-mail received no responses on the devel list. However, Alan Akin did see this and reply with some excellent comments directly to Kevin and myself. After a couple of months with no feedback we pushed on. We were able to hire Rik Faith in November and by early December dedicated a couple of weeks to working together to come up with a low level design document. Allen Akin volunteered his time in that effort, and the four of us spent every other day for two weeks on the phone and the off days thinking over and writing up our design.

By the end of 1998, we had a small amount of funding (relative to the size of the project) and a low level design in hand; however, we were still missing some key components. We needed a reference implementation of OpenGL to base our 3D drivers on. SGI had sample implementation, but they weren't ready to release it in open source, yet. They did however, release their GLX library which was very helpful. They also gave us an initial round of funding — but they understood the problem; and shared with us (after the fact) that they didn't think it could be done on the aggressive schedule and shoe string budget we had to work with. Red Hat also funded this effort. Red Hat was new to 3D graphics, and didn't realize the mountain we were trying to climb — still their support was invaluable.

The two key pieces of technology that came our way (just in time) was SGI's GLX release and Brian Paul's willingness to give us a Mesa license that was compatible with XFree86. With the two missing pieces to the puzzle finally available, we posted to the list again in February of '99. Here is a copy of our post:

Subject: SGI's GLX Source Release
From: Jens Owen (jens@precisioninsight.com)
Date: Tue, 16 Feb 1999 16:18:32 -0700 

SGI has announced their GLX source release to the open source 
community. You can read the press release at 
http://www.sgi.com/newsroom/press_releases/1999/february/opengl.html 

Precision Insight is working with SGI to incorporate their GLX source 
base into XFree86. We are also working on integrating the SGI's GLX 
code base and Brian Paul's Mesa core rendering functionality within
the XFree86 4.0 X Server development branch.

This initial GLX/Mesa integration is an effort to quickly get an early 
version of software only indirect rendering into the XFree86 4.0 
development tree. That will then be the basis for our Direct Rendering 
Infrastructure (DRI) development which will be available in mid '99. 

If you would like more detailed information about our Direct Rendering 
Infrastructure, we have posted an updated project description at 
http://www.precisioninsight.com/DRI021699.html 

Regards, 
Jens Owen 
			

This was exciting. We still didn't get much community involvement — but we did have enough money in hand to fund 3 full time developers to crank this out by the end of June of 1999. We each took a driver component and pushed forward as fast as we could. Kevin took the 3D component and tied the GLX, Mesa and a hardware implementation together. Rik took the kernel component and developed the DRMlib and our first DRM hardware implementation. I took the X Server piece and developed the DRI server extension and extended a DDX driver to be "DRI aware". We burned the midnight oil at a pace that would make Gareth proud:-) We new we had a huge task ahead. We had committed to a demo at the Linux show in the middle of May and needed to wrap up the project by the end of June (when our funded ran out). One slip up by any of us and we weren't going to be able to pull this off. We hadn't been getting much feedback from the open source community — so we just put our heads down and developed like mad men.

By the middle of May, we had a handful of design documents and we were ready for the trade show demo. We posted this to :

Subject: Direct Rendering Design Docs Available
From: Jens Owen (jens@precisioninsight.com)
Date: Wed, 12 May 1999 17:09:23 -0600 

Pointers to our DRI design docs can be found at 
http://www.precisioninsight.com/piinsights.com 

Please direct comments to glx@xfree86.org 

Regards, 
Jens 
			

The only feedback we received was two posts to correct the URL we posted. I admit we weren't too surprised. We hadn't gotten any feedback on the early designs — so why should the more detailed documents be any different. We pulled off our demo and pushed on. We needed to clean up the sources enough to get them into XFree86. We thought, if design documents aren't helping other developers understand our work; maybe the sources will. By the middle of June 1999, we had an alpha release submitted to XFree86. Here's the old announcement:

Subject: README for Direct Rendering
From: Jens Owen (jens@precisioninsight.com)
Date: Sat, 12 Jun 1999 22:51:59 -0600 

Attached is the README for the alpha release of our Direct Rendering 
Infrastructure that has been submitted to XFree86. Look for the code
in an upcoming 3.9 alpha patch release. 

Regards, 
Jens Owen 

  Direct Rendering Infrastructure Alpha release 
  --------------------------------------------- 

  Patches for the alpha release of Precision Insight's Direct Rendering 
  Infrastructure (DRI) have been submitted to XFree86. The final sample 
  implementation (SI) will be available at the end of June. The purpose 
  of this release is to allow XFree86 and others to start evaluating the 
  code. 

  *NOTE* This is an alpha release and there will be changes between now 
  and the final SI release. 

  Please direct all comments about this release to glx@xfree86.org. 

  * What comes with this release? 

	There are four main parts of this patch: 

	1. the client- and server-side DRI, 
	2. a 2D DDX driver for 3Dlabs' GMX2000, 
	3. an OpenGL client side direct rendering driver for the GMX2000,
  and 
	4. a generic kernel driver for Linux 2.2.x. 
  
	The DRI handles the communication and synchronization between the X 
	server, the client driver and the kernel driver. 

	The 3Dlabs XFree86 DDX driver has been enhanced to support the 
	GMX2000. It has also been extended to communicate with and provide 
	callbacks for the DRI. 

	The client driver implements a subset of OpenGL. The subset required 
	for id Software's Quake 2 was chosen to demonstrate the capabilities 
	of the DRI. This driver communicates with the device by filling DMA 
	buffers and sending them to the kernel driver. Note that the Gamma 
	chip implements OpenGL 1.1 in hardware, and therefore, does not use 
	the Mesa internals at this time. However, support for the majority
	of current generation of 3D hardware devices will require
	integration with Mesa, so an example DRI driver using the Mesa
	software-only pipeline was implemented (and is mostly complete for
	the alpha release). 

	The generic kernel driver handles the allocation of the DMA buffers, 
	distribution of the buffers to the clients, sending the buffers to
	the device, and the management of synchronization between the client 
	driver, the X server, and the kernel driver (this includes the
	device lock and a shared memory region). Note that hardware that
	does not support DMA or that does support special synchronization
	methods will only make use of a subset of these capabilities. 

  * What are the known problems and/or limitations of the alpha 
	release? 

	We are actively working on fixing the items listed below, and will 
	attempt to fix as many of them as possible before the SI release. 

	- The X server seg faults due to a context switching bug when there 
	  are 10 or more 3D clients running simultaneously 
	- Dynamic loading of the OpenGL client driver is not yet implemented 
	- 3D client death while holding the drawable lock causes deadlock 
	- The kernel module only works with Linux kernels 2.2.[0-5] 
	- A better authentication mechanism needs to be implemented 
	- A better DMA buffer queuing algorithm needs to be implemented 
	- A device specific shared memory region needs to be added to SAREA 
	- The DRI protocol request for the framebuffer layout needs to be 
	  extended to support FB width and depth information (for 24 vs. 32 
	  bpp, 8+24 layouts, etc) 
	- Add options for the DRI to XF86Config 

	Here are other problems that we are not going to have time to fix
	for the SI. However, we and other open source developers are going
	to continue developing and extending the DRI in follow-on projects. 

	- Direct rendering to a pixmap is not supported 
	- A more sophisticated texture management routine is required to 
	  handle texture swapping efficiently 
	- Multi-threaded OpenGL clients are not supported 
	- glXCopyContext and glXUseXFont are not supported in the DRI 
	- SwapBuffers does not wait on vertical retrace 
	- Support wait for vertical retrace in kernel driver 
	- Handling overlays is not currently supported 
	- Integrate with DBE 
	- Completing the software-only Mesa example driver 
	- Completing the other OpenGL paths for the GMX2000 
	- Support for video modes other than 640x480 in both the GMX2000 2D 
	  DDX driver and the 3D client driver 
	- More than minimal 2D acceleration of the GMX2000 2D DDX driver 
	  should be implemented 
	- Implement finer grained locking scheme in X server to improve 
	  interactivity 
	- Only grab the drawable lock and update the drawable stamp when a
	  3D window is altered 
	- The viewport does not scale properly when a 3D window is resized 
	- Double buffered 3D windows are not clipped to the screen 
	- glXSwapBuffers is not clipped to the client's viewport 
	- Only one client is allowed to use texture memory 
	- glFinish does not wait until the HW completes processing the 
	  outstanding DMA buffers 
	- Version numbers of the DDX and kernel driver are not verified 
	- Make lock available during SIGSTOP 
	- Make drmFinish work while holding the device lock 
	- Improve /proc/drm 
	- Improve documentation 
	- Improve example device-specific kernel driver (not used for SI) 

  * Where can I get more information? 

	We have made our design and implementation documents available on
	our website: 

		http://www.precisioninsight.com/piinsights.html 

	More documentation will be available with the SI release. 

  * Where should I send comments? 

	Please send all comments and questions to the glx@xfree86.org list 
			

Wow, we had made it. The base DRI infrastructure had been released on an near impossible budget and dead line. We were excited to have crossed this bridge — but from the list of limitations outlined in our README above, we new there was still a lot of work to be done. We needed more funding, more work on the infrastructure and more complete driver implementations to move the DRI forward. Daryll Strauss had joined our team just before the trade show in May and was quickly ramping up on the DRI. As the initial 3 developers colapsed in a heap by the end of June; Daryll was able to pick up the slack and push the DRI on another amazing evolution with an impossible schedule. 3Dfx hired us to develop a DRI driver for the Banshee and Voodoo2 chipsets and they wanted a demo by the SigGraph trade show in August of 1999. This seemed impossible in my opinion — but Daryll had the experience of implementing the first complete hardware accellerated OpenGL under Mesa for Linux under his belt. In the past, he had used 3Dfx's Glide library to achieve great results. Now, he attacked the DRI, learned it strengths, and molded around it's weaknesses to developed a demo of the first complete 3D driver for the DRI in just two short months.

That summer, Intel had also commisioned us to develop a 3D driver for the i810 chipset. They didn't have the head start of existing 2D drivers and a ported Glide library — but they were serious about doing Linux right. They wanted complete 2D drivers for the current XFree86 release, first. We were able to bring Keith Whitwell onto the team. Keith knew Mesa well, and had been a key contributor to the first native Mesa drivers under the Utah-GLX project. Keith spun up on 2D XFree86 drivers in no time flat and developed Intel's i810 2D drivers for XFree86 3.3 and 4.0. Then, when the 2D drivers were complete he used his wizardry to develop the first cut of fully native Mesa DRI driver in just a few short weeks. Keith's focus on performance and ability to quickly generate complex 3D drivers was nothing short of amazing — however, it is his consumate dedication to open development that helped move the DRI forward the most. Keith saw first hand how well a simple framework like the Utah-GLX project was able to foster new graphics talent — and he was the initial driving force behind the DRI project being moved to completely open source repository and mailing lists. The entire team embraced his ideals; and the DRI Source Forge project was born.

By the end of the summer of 1999; Wall Street had found Linux and no less than four major graphics hardware vendors had secured our services for a 3D driver under Linux. We had committed to have complete driver suites in place for the latest chipsets from 3Dfx, Intel, ATI and Matrox by early 2000. This required a large effort across the team and some new hands as well. We picked up Jeff Hartmann, an AGP specialist — who enabled us to utilized true AGP busmastering for our drivers. Next we added Brian Paul to our team — as the author of Mesa, his knowledge was second to none and his dedication to OpenGL conformance helped our drivers reach a higher level of completeness and quality.

Brian had a history of working well with members of the OpenGL Architecture Review Board and usually provided the first implementations of new ARB approved extensions via his Mesa software renderer. He was able to quickly drive forward a standard for dynamically resolving driver extensions at run time and implement a nice jump table mechanism to allow multiple DRI drivers to be handled via a single OpenGL library. These mechanisms were integrated into our drivers and OpenGL library just in time for the XFree86 4.0 release.

The XFree86 4.0 release had been our target platform since the early design days of the DRI. We wanted (and needed) to be closely integrated with the standard for open source windowing software — XFree86. David Dawes, a founding member and president of XFree86, joined our team in January of 2000 and helped us bring the DRI project into even closer alignment with the needs of XFree86.

With a heroic effort by Kevin, Rik, Daryll, Keith, Jeff, Brian and David we were able to deliver no less than 4 complete driver suites for the XFree86 4.0 release in early 2000. This moved the DRI from the status of "sample framework" to a solid 3D platform in eight short months. We had moved from a "make annoucements" on progress every few months mode to a fully open development process hosted at SourceForge.

A few months later Precision Insight was aquired by VA Linux Systems. The team grew further to include some additional fantastic developers: Gareth Hughes, Alan Hourihane and Nathan Hand. We took more steps forward in the progression of the DRI — but alas VA was not meant to be in the 3D Linux business.

Today, the team has split up and moved forward in a few different directions. Some of the team went to work for Red Hat (Alan, Kevin and Rik); Gareth is working for NVidia; and Brian, Keith and David have started a new company called Tungsten Graphics with Frank Lamonica and myself. Jeff has gone back to school and Nathan is working on other projects from Australia.

Hopefully this background can give you a perspective for how the DRI has always been rooted in the open source community and how we have evolved to using more and more effective open development techniques. I sincerely hope we can find and provide the needed catalysts for bringing new developers into the exciting technical area of 3D graphics development.

 
--Jens Owen 

Notes

[1]

Extracted and slightly edited from a email between Jens Owen and Matt Sottek from Intel.