head	1.1;
access;
symbols
	libdrm-1_0_4:1.1;
locks; strict;
comment	@# @;


1.1
date	2003.06.25.14.40.08;	author jrfonseca;	state Exp;
branches;
next	;


desc
@@


1.1
log
@Switch the source format to DocBook XML.
@
text
@<?xml version='1.0' encoding='iso-8859-1'?>

<sect1 id="getting-started">
	<title>Getting Started</title>
	
	<sect2 id="how-get-started">
		<title>How do I get started with development?</title>
		
		<para>
		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.
		</para>
		
		<para>
		Then you can continue by checking out the <ulink url="http://dri.sourceforge.net/doc/cvs.html">DRI CVS tree</ulink>.
		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.
		</para>
		
		<para>
		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 <ulink url="http://sourceforge.net/tracker/?group_id=387">
		SourceForge bug tracker</ulink> for 
		open issues. That is a good place to find an issue that you can fix by 
		submitting a patch.
		</para>
		
		<para>
		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.
		</para>
		
		<para>
		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?
		</para>
		
		<para>
		Also, don't be shy about asking questions on the 
		<ulink url="http://lists.sourceforge.net/mailman/listinfo/dri-devel">
		dri-devel newsgroup</ulink>. The main purpose of the newsgroup is the 
		discussion of development issues. So, feel 
		free to ask questions.
		</para>
	</sect2>

	<sect2>
		<title>How do I submit a patch?</title>

		<para>
		There are two ways you can submit a patch.
		</para>

		<para>
		Preferably you will submit the patch through our <ulink url="http://www.sourceforge.net/projects/dri">SourceForge project page</ulink>. 
		That way we can easily find your user id to add you to the project as a 
		developer and give you CVS access.
		</para>

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

		<para>
		In any case, make sure you explain clearly what your patch is for.
		</para>
	</sect2>

	<sect2 id="driver-constitution">
		<title>How is constituted a DRI driver?</title>
		
		<para>
		All DRI drivers are made up of 3 parts:
		</para>
		
		<itemizedlist>
			<listitem>
				<para>
				A DRI aware 2D driver which lives in
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/programs/Xserver/hw/xfree86/drivers/">
					<filename class="directory">xc/programs/Xserver/hw/xfree86/drivers/</filename>
				</ulink>
				usually in a file <filename>*_dri.[ch]</filename>.
				</para>
			</listitem>
			
			<listitem>
				<para>
				A DRI aware 3D driver based on Mesa which lives in
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/lib/GL/mesa/src/drv/">
					<filename class="directory">xc/lib/GL/mesa/src/drv/</filename>
				</ulink>
				</para>
			</listitem>
			
			<listitem>
				<para>
				A kernel module which lives in
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/programs/Xserver/hw/xfree86/os-support/linux/drm/">
					<filename class="directory">xc/programs/Xserver/hw/xfree86/os-support/linux/drm/</filename>
				</ulink>
				</para>
			</listitem>
		</itemizedlist>
	</sect2>
	
	<sect2 id="x11-knowledge">
		<title>Do I need to understand the X11 in order to help?</title>
	
		<blockquote>
			<attribution>Gareth Hughes</attribution>
			
			<para>
			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
			(<filename>xc/lib/GL/mesa/src/drv/*</filename>).  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&hellip;
			</para>
		</blockquote>
	</sect2>

	<sect2 id="suggested-reading">
		<title>Suggested Reading</title>
		
		<para>You may find in the <link linkend="references">References</link> section an extensive list of documents. 
		This section will give you a guide to how you should approach the reading of these resources.</para>
		
		<sect3 id="reading-beginners">
			<title>For beginners...</title>
			
			<para>
			There is a wide range of concepts that one is required to handle for making a DRI driver.
			As a beginner you don't really need to fully understand them &mdash; just a basic understanding which enables you to get the global picture.
			You should skim trhough all the documents referred below, giving more attention to the parts that your curiosity and/or ignorance point you to.
			</para>
			
			<para>
			The first document you should read is this FAQ. 
			Not because it's more important than the rest, but because is full of references and simple explanations that will provide the basic knowledge you need to guide yourself.
			</para>
			
			<para>
			There are several topics you must address:
			</para>
			
			<itemizedlist>
				<listitem>
					<para>
					<emphasis role="strong">3D cards workings</emphasis>
					Since a 3D driver and the OpenGL API are basically abstractions to the 3D graphics cards abilities, knowing how a 3D card works will make you better understand the formers.
					<link linkend="barron01"><citation>Barron01</citation></link> and
					<link linkend="salvator01"><citation>Salvator01</citation></link> give an excelent overview of that.
					</para>
				</listitem>
				
				<listitem>
					<para>
					<emphasis role="strong">OpenGL API</emphasis>
					The DRI drivers, althought they make no such claim, they aim to be as conformant as possible to the OpenGL API.
					The best reading is indeed the <link linkend="opengl-1.3-spec">OpenGL Specification</link>. As Brian Paul said: 
					<emphasis><quote>The RedBook is for OpenGL users.  The spec is more for the implementors.</quote></emphasis>
					</para>
				</listitem>
				
				<listitem>
					<para>
					<emphasis role="strong">Low-level programming</emphasis>
					Since you'll be dealing with the guts of the hardware and the OS you should read 
					<link linkend="ldd"><citation>LDD</citation></link>
					which addresses all the details of writing a device driver, covering issues such as I/O, DMA, memory organization on the Linux kernel perspective.
					<link linkend="tlk"><citation>TLK</citation></link> and
					<link linkend="lkmpg"><citation>LKMPG</citation></link> are
					also good references.
					</para>
				</listitem>
				
				<listitem>
					<para>
					<emphasis role="strong">DRI and XFree86 architecture</emphasis>
					This FAQ will give you an good and uptodate overview of the DRI architecture, but since not all information of the DRI documentation is contained you should give 
					a quick look trhough <ulink url="http://dri.sourceforge.net/documentation.phtml">it</ulink> since you may need it for later reference. 
					The <link linkend="xfree86-design">XFree86 architecture</link> is also important.
					</para>
				</listitem>
			</itemizedlist>
		</sect3>

		<sect3 id="reading-reference">
			<title>For reference...</title>
			
			<para>
			Besides of reading more thorougly the above documents, many times one founds that the source code is the best reference available as the documentation is out-of-dat or non-existant.
			</para>
			
			<para>
			To master the tools to quickly find a piece of information on a source tree as big as is DRI is a key aspect. 
			Use <ulink url="http://www.gnu.org/software/findutils/findutils.html">find and locate</ulink> to quickly get to the files you search.
			Use <ulink url="http://www.gnu.org/software/grep/doc/grep.html">grep</ulink> for searching a for a particular variable or piece of text. 
			Alternatively you can use specific tools for code navigation such as <ulink url="http://cscope.sourceforge.net">cscope</ulink> and 
			<ulink url="http://sources.redhat.com/sourcenav/">Source Navigator</ulink>.
			</para>
			
			<para>
			Another source of information is the source of the drivers other than the one you interested. 
			Since the DRI drivers are more or less in tune with each other you can learn alot by comparing the sources.
			Use <ulink url="http://www.gnu.org/software/diffutils/diffutils.html">diff</ulink> or 
			<ulink url="http://xxdiff.sourceforge.net">xxdiff</ulink> for that.
			</para>
		</sect3>
	</sect2>
	
	<sect2 id="new-driver">
		<title>I want to start the development of a new driver. Which one should I took as template?</title>
		
		<para>
		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.
		</para>
		
		<para>
		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).
		</para>
		
		<para>
		There are a few possibilities you have to consider:
		</para>
		
		<itemizedlist>
			<listitem>
				<para>
				If your card has a &DMA; model which is secure (there is no way that the client
				can emit instructions which cause writes to system memory, for instance), the
				current i810 driver is what you should examine.
				</para>
			</listitem>
				
			<listitem>
				<para>
				If your card has a &DMA; buffers can cause writes
				to PCI space), look at the current mga driver.
				</para>
			</listitem>
				
			<listitem>
				<para>
				If your card has a &MMIO; model which is secure, and there is no vertex
				buffer or &DMA; buffer mechanism, the i810 driver is probably the closest thing
				to look at for state management, but you will need to take a different
				approach to emitting cliprects &mdash; the tdfx driver has some examples of this.
				</para>
			</listitem>
				
			<listitem>
				<para>
				If your card has a &MMIO; model which is <emphasis>insecure</emphasis> and there is no
				vertex buffer or &DMA; buffer mechanism, you are really in a world of hurt&hellip;
				There are ways around most problems, but hopefully we don't need to get into
				details.
				</para>
			</listitem>
		</itemizedlist>
		
		<para>
		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, e.g., the bit of memory which holds a process' UID number.
		</para>
		
		<para>
		Most hardware seems to have been designed for consumer versions of Windows, 
		which don't really have a security model.
		</para>
		
		<para>
		So, you need to verify there is no mechanism to write to PCI space (in any way
		or form).
		</para>
		
		<para>
		If there is no &DMA; interface &mdash; as long as the card is secure &mdash; 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 &mdash; 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 &DMA;.  You will
		need to look at how the tdfx driver emits cliprects in the triangle routines &mdash; 
		you'll need to do something similar.
		</para>
	</sect2>
	
	<sect2 id="irc-meetings">
		<title>IRC meetings</title>

		<para>
		Sometime ago it was decided to make
		a weekly IRC meeting would help where new developers can ask the experts, and
		each other, questions about DRI, XFree or 3D graphics.
		</para>
		
		<sect3>
			<title>When it will be the next meeting?</title>
			
			<para>
			The meetings are scheduled to every Monday at 2100 UTC on irc.openprojects.net channel #dri-devel.
			</para>
		</sect3>
		
		<sect3>
			<title>Where can I get the log of the meeting?</title>
			
			<para>
			Logs of all developer IRC meetings are available 
			<ulink url="http://dri.sourceforge.net/IRC-logs/">here</ulink>.
			</para>
		</sect3>
	</sect2>
	
	<sect2 id="nda">
		<title>Access to NDA documentation</title>
		
		<para>
		This section is about NDA and the mechanisms involved.
		<footnote>
			<para>
			Contributed by Mike Harris.
			</para>
		</footnote>
		</para>
		
		<sect3 id="nda-definition">
			<title>What does NDA stands for?</title>
			
			<para>
			NDA stands for <emphasis>Non Disclosure Agreement</emphasis>.  This 
			means, when you agree to an NDA, you are agreeing to not disclose 
			the information you are receiving, to parties other than whom are 
			listed in the agreement you are signing or agreeing to.
			</para>
		</sect3>
		
		<sect3>
			<title>Doesn't XFree86.org have NDA documentation?</title>
			
			<para>
			XFree86.org has documentation for some pieces of 
			video hardware that was obtained under NDA, and they are not able 
			to distribute that documentation to other people freely or else 
			that pretty much negates the whole point of an NDA.
			</para>
			
			<para>
			As such, in order to obtain access to this NDA information, 
			XFree86.org requires that you become a member of XFree86.org 
			first, and agree to the XFree86.org NDA.  Once you've 
			agreed to the NDA, and have been accepted as a developer, then 
			you can access the documentation that XFree86.org has under NDA.
			</para>
			
			<para>
			Please note, that the above process does <emphasis>not</emphasis> get you access to 
			the documentation of all of a particular hardware. Whatever is not on the ftp site, is not available.  
			You must then acquire whatever NDAs you need on your own.  
			</para>
			
			<para>
			In order to get specific hardware documentation, you must usually become a developer 
			relations member of the hardware vendor.  If you're not an XFree86 member however, then 
			you very highly likely going to be refused by a 
			given hardware manufacturer for consideration of NDA unless 
			you meet some other criterion, such as working for some graphics company, or a game developer or 
			such.
			</para>
		</sect3>
		
		<sect3>
			<title>How do I become member of XFree86.org?</title>
			
			<para>
			In order to be accepted into the project you need to 
			follow the steps described <ulink url="http://www.xfree.org/developer.html">here</ulink> and 
			submit a bugfix or otherwise contribute to the XFree86 codebase.
			</para>
			
			<para>
			To join The XFree86 Project as a non-voting member you need to 
			first submit a documented fix to our code-base at
			<email>fixes@@xfree86.org</email>. Once this fix is accepted and committed to
			our repository,
			with or without minor corrections, please send an email to 
			<email>signup@@xfree86.org</email> stating the reason you wish to become a 
			member and what area of XFree86 you want to contribute. If instead you
			are looking for a meeting place or discussion group, give our 
			open groups a look; they may be more to your suiting. All 
			XFree86 groups, whether open or member-controlled, are unmoderated.
			</para>
		</sect3>
		
		<sect3>
			<title>What are the steps that one should take to get NDA documentation?</title>
			
			<orderedlist>
				<listitem>
					<para>
					Fix some bugs in XFree86, or add some new features to it
					</para>
				</listitem>
				
				<listitem>
					<para>
					Submit your fixes/patches to fixes@@xfree86.org
					</para>
				</listitem>
				
				<listitem>
					<para>
					Apply to XFree86.org to become a member as per the information 
					on the xfree86.org website.
					</para>
				</listitem>
				
				<listitem>
					<para>
					If accepted, which will likely be the case since very few 
					people are ever refused, then you will be offered an NDA 
					agreement.  You must agree to this agreement in order to 
					proceed further.
					</para>
				</listitem>
				
				<listitem>
					<para>
					Once you've agreed to the NDA, then you will be given various 
					other information details including access to the private 
					website/ftpsite/mailinglists and whatnot.  The ftpsite 
					contains various datasheets for some hardware which is under 
					NDA.  You can now access this information, but must NOT 
					redistribute it to anyone.
					</para>
				</listitem>
				
				<listitem>
					<para>
					At some point after this, you can apply to the hardware vendor developer 
					relations, and let them know you are a registered XFree86 
					developer.
					</para>
				</listitem>
			</orderedlist>
			
			<para>
			At that point, the hardware vendor will decide whether or not to offer you access
			to the documentation.  Very few people if
			any are refused access to the documentation who have shown 
			initiative to follow the above steps, and to actively contribute 
			to XFree86.
			</para>
			
			<para>
			Also note that what is written above is not <quote>the law</quote>.  It 
			comes with no guarantees whatsoever.  It is just a general 
			guideline to follow to get from point A to point B.  People who 
			go out of their way to contribute to XFree86 by working on 
			bugfixes in <emphasis>any</emphasis> part of the code/documentation, etc. by showing 
			their own initiative and <quote>just doing it</quote>, are much more likely to 
			be accepted as a developer than those who just whine and say <quote>I 
			cant get docs so I cant fix the code</quote>.  Find something that you 
			can fix <emphasis>now</emphasis> with the skills you <emphasis>have</emphasis> and the information you 
			<emphasis>have</emphasis>, and contribute it back to XFree86.  In particular, if 
			you're interested in a particular vendor's hardware, read the 
			driver source code, and try to understand it.  Read the <emphasis>design</emphasis>
			document in the XFree86 source code.  Many bugs can be found and 
			fixed without having the hardware documentation, and many of 
			those even without having the actual hardware.
			</para>
			
			<para>
			Out of all of the people interested in working on XFree86 or DRI, 
			people generally fall into two categories:
			</para>
			
			<orderedlist>
				<listitem>
					<para>
					People who show initiative and do stuff, working with what 
					hardware, tools and documentation that <emphasis>are</emphasis> available to 
					them, and asking questions about problems they encounter while 
					trying to fix a given bug or work on a piece of driver code.
					</para>
				</listitem>
			
				<listitem>
					<para>
					People who have done nothing at all, but are interested in 
					doing so, but whom probably have not even looked at the source 
					code, or even tried to fix any bugs, assuming that they must 
					have the documentation first or it is not possible to 
					contribute to anything.  Many of whom complain about lack of 
					documentation, having to agree to NDAs and whatnot.
					</para>
				</listitem>
			</orderedlist>
			
			<para>
			While #2 people often have legitimate complaints, many of the
			things I have seen people complain about are static items, at
			least for the time being.  It is generally the #1 people who
			show the most initiative, and hack away on their own, that end up
			producing results, and also end up meeting the general
			unofficial guidelines mentioned above.
			</para>
			
			<para>
			Summary: <emphasis>JUST DO IT</emphasis>
			</para>
		</sect3>
		
		<sect3>
			<title>What're the reasons behind NDA?</title>
			
			<blockquote>
				<attribution>Mike A. Harris</attribution>
				
				<para>
				I'd just like to comment a bit about the mechanisms involved
				here, at least as I myself see them.  It is not limited to any
				particular vendor nor to any particular individual seeking
				information.  Also, my comments are solely my own, and do not in
				any way reflect any opinions of my employer, or of any hardware
				vendors, etc.
				</para>
				
				<para>
				In a perfect world, all vendors would just allow access to their
				documentation outright and freely.  However, we aren't in that
				utopia yet, and they do indeed control access to their
				documentation, whether or not individuals like that or not.  So,
				to <emphasis>get</emphasis> to that documentation, we very much need to play by
				<emphasis>their</emphasis> rules.  Again, I speak of no particular company here, or
				individuals.
				</para>
				
				<para>
				If they want to restrict access to information, then IMHO, there
				needs to be <emphasis>some</emphasis> mechanism in place to determine who gets
				documentation, and who does not get it.  If it were as simple as:
				Joe Blow signs up, is automatically accepted without any
				question, clicks on NDA agreement, and then gets the docs, they
				might as well just publish the docs on their website freely for
				anyone to download anyways, as they wouldn't be restricting
				information at all.
				</para>
				
				<para>
				Who should they give their docs to?  Do they want just anyone
				having the docs?  Or do they want competent developers that are
				most likely to <emphasis>really</emphasis> use the information to produce real
				results?
				</para>
				
				<para>
				What metric gauges the decision?  Does Joe programmer have a CS
				degree in 3D work, thus more likely to successfully use the
				information to complete some open source work?  Is he a video
				game programmer?  What has he done?  Or is he just someone who is
				wanting to help, and is good intentioned, but might not actually
				have the skills and/or time to truly contribute?  How do they
				know?  For all they know, someone could say they are working on
				fixing a bug in XFree86, however actually they are working for a
				competitor for example.  Who knows what the logic behind it all,
				or cares.  Either way, some metric is needed to decide how to
				divulge information.
				</para>
				
				<para>
				If the purpose of using an NDA is to restrict access to
				information, yet let <emphasis>capable</emphasis> individuals access that
				information to yield working results, and thus improve support
				for and promote a hardware vendor's product well, there needs to
				be <emphasis>some</emphasis> metric with which to gauge someone, and whether they are
				<emphasis>truly</emphasis> capable, or whether they are just <quote>good intentioned</quote>.
				</para>
				
				<para>
				If someone is working for a graphics company for example, is
				affiliated with some past work such as DRI, XFree86, perhaps has
				their name in the kernel credits for graphics work, or has some
				<emphasis>credential</emphasis> showing their capabilities, then it would stand to
				reason the chances are much higher that they could use the
				information and produce results.  Probability-wise that is.
				</para>
				
				<para>
				If someone is not working for a company who does graphics, or is
				writing video drivers, or affiliated with XFree86 and/or DRI, or
				some other similar thing, they <emphasis>could</emphasis> (not would, just <emphasis>could</emphasis>)
				potentially be a higher risk of information leakage IMHO.  It
				stands to reason then, that a company may want to see some
				credentials before allowing access to information.  By having
				people become XFree86 members first, I think it is a <emphasis>very</emphasis> good
				metric to see who is serious on working on code.  XFree86 does
				not have difficult membership requirements, and any programmer
				who is capable of taking register level documentation from a
				hardware manufacturer, and producing useful results from it, is
				also <emphasis>very</emphasis> capable of quickly becoming an XFree86 member.
				</para>
				
				<para>
				To do so, one need only fix a bug in XFree86, or perhaps add a
				feature, even something small.  It is a small measure of one's
				capabilities to do the job.  Once someone has passed the test of
				writing some small patch, that fixes something in X, they have
				shown <emphasis>some</emphasis> level of troubleshooting skill, some level of
				proficiency, and are <emphasis>much</emphasis> more likely to also continue to
				contribute to the project in the future.  By passing that test,
				one can elect to join XFree86 as a member, which involves reading
				a web page, firing off an email, and then bouncing a few emails,
				agreeing to the XFree86 NDA.
				</para>
				
				<para>
				Once one is an XFree86 member, they open up a lot of doors,
				including access to information that XFree86 has under NDA, and
				other private stuff.  One can then come to a hardware vendor,
				asking for technical specifications under NDA with something more
				than <quote>I know how to program C, and have good intentions</quote>, they
				can say, <quote>I am an XFree86 member wanting to add support for foo,
				and/or fix bar in driver baz on your fooblaster card.</quote>  I don't
				know of any XFree86 developer who has been refused information
				by vendors who support open source after having adequately went
				through the right channels, and proved that they are truly
				serious about the work they'd like to do, by passing a few litmus
				tests.
				</para>
				
				<para>
				In all honesty, I think if someone thinks fixing a bug in XFree86
				and becoming a member is too much of a hassle, then they are most
				likely not going to come through on any serious code at all
				anyways, and are thus more likely to be a information leak to
				a particular hardware vendor than an asset.
				</para>
				
				<para>
				People certainly don't need to jump into the lake completely, it
				makes at least some sense to me that they should commit to
				dipping their leg in up to their knee, rather than just putting
				their toe in, and wanting full scuba gear.  Scuba equipment given
				to them, may end up sitting on a shelf, rather than being used
				for whatever it is scuba divers use their equipment for.
				</para>
				
				<para>
				OK.. that was an oddball analogy, but it does the job.  ;o)
				</para>
				
				<para>
				My above thoughts on the logic involved behind these processes,
				may be way off mark, but that is what I've come up with, while
				watching the processes at work, and trying to look at the
				situation from the various different sides involved.
				</para>
				
				<para>
				I guess it could be stated more like this:
				</para>
				
				<blockquote>
					<para>
					You can get much further with a smile and a few bugfixes
					accepted into the code base, than you can get with a smile
					alone.
					</para>
				</blockquote>
				
				<para>
				You can quote me on that.  ;o)
				</para>
			</blockquote>
		</sect3>
	</sect2>
	
	<sect2 id="dri-history">
		<title>What's the DRI history?</title>
	
		<blockquote>
			<attribution>Jens Owen</attribution>
			<para>
			This is mostly a history of the DRI
			<footnote>
				<para>
				Extracted and slightly edited from a email between Jens Owen and Matt Sottek from Intel.
				</para>
			</footnote>.
			If you're interested, print it out and snuggle up by the fire&hellip;
			</para>

			<para>
			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.
			</para>
			
			<para>
			So, Kevin and I sat down and wrote the <ulink url="http://dri.sourceforge.net/doc/design_high_level.html">
			high level design document</ulink>, 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
			<email>devel@@xfree86.org</email> mailing list in September of 1998:
			</para>
			
			<programlisting>
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
			</programlisting>
			
			<para>
			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.
			</para>
			
			<para>
			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 &mdash; 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 &mdash; still their support was
			invaluable.
			</para>
			
			<para>
			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 <email>devel@@xfree86.org</email> list again
			in February of '99.  Here is a copy of our post:
			</para>
			
			<programlisting>
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 
			</programlisting>
			
			<para>
			This was exciting.  We still didn't get much community involvement &mdash; 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 knew 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 &mdash; so we just put our heads down and developed like
			mad men.
			</para>
			
			<para>
			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 <email>devel@@xfree86.org</email>:
			</para>
			
			<programlisting>
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 
			</programlisting>

			<para>
			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 &mdash; 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 <emphasis>alpha</emphasis>
			release submitted to XFree86.  Here's the old announcement:
			</para>
			
			<programlisting>
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 
			</programlisting>
			
			<para>
			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 &mdash; but from the list of limitations outlined in our
			<filename>README</filename> above, we knew 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 collapsed 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 &mdash; but Daryll had the experience of
			implementing the first complete hardware accelerated 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 <emphasis>complete</emphasis> 3D driver for the DRI in just two short months.
			</para>
			
			<para>
			That summer, Intel had also commissioned 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 &mdash; 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 <emphasis>native</emphasis>
			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 <emphasis>native</emphasis> 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 &mdash; however, it is his consummated 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 &mdash; 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.
			</para>
			
			<para>
			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 &mdash; who
			enabled us to utilized true AGP busmastering for our drivers.  Next we
			added Brian Paul to our team &mdash; 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.
			</para>
			
			<para>
			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.
			</para>
			
			<para>
			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 <emphasis>the</emphasis> standard for open source windowing software &mdash; 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.
			</para>
			
			<para>
			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 <quote>sample framework</quote> to a solid 3D platform in eight short months.  We
			had moved from a <quote>make announcements</quote> on progress every few months mode
			to a fully open development process hosted at <ulink url="http://dri.sourceforge.net">SourceForge</ulink>.
			</para>
			
			<para>
			A few months later Precision Insight was acquired 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 &mdash; but alas VA was not meant to be
			in the 3D Linux business.  
			</para>
			
			<para>
			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.
			</para>
			
			<para>
			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.
			</para>
		</blockquote>
	</sect2>
</sect1>
@