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


1.1
date	2003.06.25.14.40.07;	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="hardware">
	<title>Hardware Specific</title>

	<sect2 id="agp">
		<title>AGP</title>
		
		<sect3 id="agp-definition">
			<title>What is the AGP?</title>
			
			<para>
			AGP is a dedicated high-speed bus that allows the graphics controller to move large amounts of data directly from system memory. 
			Uses a Graphics Address Re-Mapping Table (GART) to provide a physically-contiguous view of scattered pages in system memory for DMA transfers.
			</para>
			
			<para>
			With AGP, main memory is specifically used for advanced three-dimensional features, such as textures, alpha buffers, and z-buffers.
			</para>
			
			<para>
			There are two primary AGP usage models for 3D rendering that have to do with how data are partitioned and accessed 
			<citation>AGPIS</citation>, 
			and the resultant interface data flow characteristics.
			</para>
			
			<glosslist>
				<glossentry>
					<glossterm>DMA</glossterm>
					
					<glossdef>
						<para>
						In the  DMA  model, the primary graphics memory is the local memory associated with the accelerator, referred to as  local frame buffer. 
						3D structures are stored in system memory, but are not used (or  executed ) directly from this memory; rather they are copied to primary (local) memory (the  DMA  operation) to which the rendering engine's address generator makes its references. 
						This implies that the traffic on the A.G.P. tends to be long, sequential transfers, serving the purpose of bulk data transport from system memory to primary graphics (local) memory. 
						This sort of access model is amenable to a linked list of physical addresses provided by software (similar to operation of a disk or network I/O device), and is generally not sensitive to a non-contiguous view of the memory space. 
						</para>
					</glossdef>
				</glossentry>
				
				<glossentry>
					<glossterm>execute</glossterm>
					
					<glossdef>
						<para>
						In the  execute  model, the accelerator uses both the local memory and the system memory as primary graphics memory. 
						From the accelerator's perspective, the two memory systems are logically equivalent; any data structure may be allocated in either memory, with performance optimization as the only criteria for selection. 
						In general, structures in system memory space are not copied into the local memory prior to use by the accelerator, but are  executed in place. 
						This implies that the traffic on the A.G.P. tends to be short, random accesses, which are not amenable to an access model based on software resolved lists of physical addresses. 
						Because the accelerator generates direct references into system memory, a contiguous view of that space is essential; however, since system memory is dynamically allocated in random 4K pages, it is necessary in the execute model to provide an address mapping mechanism that maps random 4K pages into a single contiguous, physical address space.
						</para>
					</glossdef>
				</glossentry>
			</glosslist>
			
			<note>
				<para>
				The A.G.P. supports both the  DMA  and  execute  models. 
				However, since a primary motivation of the AGP is to reduce growth pressure on local memory, the  execute  model is the design center. 
				</para>
			</note>
			
			<para>
			AGP also allows to issue several access requests in a pipelined fashion while waiting for the data transfers to occur. 
			Pipelining access requests results in having several read and/or write requests outstanding in the corelogic's request queue at any point in time.
			</para>
		</sect3>

		<sect3 id="gart-definition">
			<title>What is the GART?</title>
			
			<para>
			The execute model interface specification requires a physical-to-physical address remapping mechanism which insures the graphics accelerator (an AGP master) will have a contiguous view of graphics data structures dynamically allocated in system memory.
			</para>
			
			<para>
			This address remapping is accomplished via a memory-based table called the Graphics Address Remapping Table (GART) and used ( walked ) by the corelogic to perform the remapping. 
			In order to avoid compatibility issues and allow future implementation flexibility, this mechanism is specified at a software (API) level. 
			In other words, the actual GART table format is not specified; rather it is abstracted to the API by a HAL or miniport driver that must be provided with the corelogic.
			</para>
			
			<note>
				<para>
				This remapping function should not be confused in any way with the system address translation table mechanism. 
				While some of the concepts are similar, these are completely separate mechanisms which operate independently, under control of the operating system.
				</para>
			</note>
			
		</sect3>
		

		<sect3 id="agp-moreinfo">
			<title>Where can I get more info about AGP?</title>
			
			<para>
			Check the 
			<ulink url="http://www.agpforum.org/faq_ans.htm">AGP Implementors Forum Q&amp;A</ulink> for more frequently asked questions about AGP.
			There also is a section about AGP on <citation>Barron01</citation>.
			</para>
			
			<para>
			Intel provides Accelerated Graphics Port Interface Specification <link linkend="agpis"><citation>AGPIS</citation></link>.
			</para>
		</sect3>

		<sect3 id="agp-xfree86">
			<title>Why not use the existing XFree86 AGP manipulation calls?</title>
			
			<para>
			You have to understand that the DRI functions have a different purpose
			then the ones in XFree.  The DRM has to know about AGP, so it talks to
			the AGP kernel module itself.  It has to be able to protect certain
			regions of AGP memory from the client side 3D drivers, yet it has to
			export some regions of it as well.  While most of this functionality
			(most, not all) can be accomplished with the <filename>/dev/agpgart</filename> interface, it
			makes sense to use the DRM's current authentication mechanism.  This
			means that there is less complexity on the client side.  If we used
			<filename>/dev/agpgart</filename> then the client would have to open two devices,
			authenticate to both of them, and make half a dozen calls to agpgart,
			then only care about the DRM device.
			</para>
			
			<note>
				<para>
				As a side note, the XFree86 calls were written after the DRM functions.
				</para>
			</note>
			
			<para>
			Also to answer a previous question about not using XFree86 calls for
			memory mapping, you have to understand that under most OSs (probably
			Solaris as well), XFree86's functions will only work for root privileged
			processes.  The whole point of the DRI is to allow processes that can
			connect to the X server to do some form of direct to hardware rendering.
			If we limited ourselves to using XFree86's functionality, we would not be
			able to do this.  We don't want everyone to be root.
			</para>
		</sect3>
        
		<sect3 id="agp-using">
			<title>How do I use AGP?</title>
			
			<para>
			You can also use <ulink url="http://dri.sourceforge.net/res/testgart.c">this</ulink> test program as a bit more documentation as to how agpgart is used.
			</para>
		</sect3>

		<sect3>
			<title>How to allocate AGP memory?</title>
		
			<para>
			Generally programs do the following:
			</para>
		
			<orderedlist>
				<listitem>
					<para>
					open /dev/agpgart
					</para>
				</listitem>
		
				<listitem>
					<para>
					ioctl(ACQUIRE)
					</para>
				</listitem>
		
				<listitem>
					<para>
					ioctl(INFO)     to determine amount of memory for AGP
					</para>
				</listitem>
		
				<listitem>
					<para>
					mmap the device
					</para>
				</listitem>
		
				<listitem>
					<para>
					ioctl(SETUP)    to set the AGP mode
					</para>
				</listitem>
		
				<listitem>
					<para>
					ioctl(ALLOCATE) a chunk o memory, specifying offset in aperture
					</para>
				</listitem>
		
				<listitem>
					<para>
					ioctl(BIND)     that same chunk o memory
					</para>
				</listitem>
			</orderedlist>
		
			<para>
			Every time you update the GATT, you have to flush the cache and/or
			TLBs.  This is expensive.  Therefore, you allocate and bind the pages
			you'll use, and mmap() just returns the right pages when needed.
			</para>
		
			<para>
			Then you need to have a remap of the AGP aperture in the kernel which
			you can access.  Use ioremap to do that.
			</para>
			
			<para>
			After that you have access to the AGP memory.  You probably want to make
			sure that there is a write combining MTRR over the aperture.  There is
			code in <filename>mga_drv.c</filename> in our kernel directory that shows you how to do that.
			</para>
		</sect3>

		<sect3>
			<title>
			If one has to insert pages he needs to check for -EBUSY
			errors and loop through the entire GTT. Wouldn't it be better if
			the driver fills up pg_start of agp_bind structure instead of
			user filling up?
			</title>

			<para>
			All this allocation should be done by only one process.  If you need
			memory in the GTT you should be asking the Xserver for it (or whatever
			your controlling process is).  Things are implemented this way so that
			the controlling process can know intimate details of how memory is laid
			out.  This is very important for the I810, since you want to set tiled
			memory on certain regions of the aperture.  If you made the kernel do
			the layout, then you would have to create device specific code in the
			kernel to make sure that the backbuffer/dcache are aligned for tiled
			memory.  This adds complexity to the kernel that doesn't need to be
			there, and imposes restrictions on what you can do with agp memory.
			Also, the current Xserver implementation (4.0) actually locks out other
			applications from adding to the GTT.  While the Xserver is active, the
			Xserver is the only one who can add memory.  Only the controlling
			process may add things to the GTT, and while a controlling process is
			active, no other application can be the controlling process.
			</para>
			
			<para>
			Microsoft's VGART does things like you are describing I believe.  I
			think its bad design.  It enforces a policy on whoever uses it, and is
			not flexible.  When you are designing low level system routines I think
			it is very important to make sure your design has the minimum of
			policy.  Otherwise when you want to do something different you have to
			change the interface, or create custom drivers for each application that
			needs to do things differently.
			</para>
		</sect3>
		
		<sect3>
			<title>How does the DMA transfer mechanism works?</title>
			
			<para>
			Here's a proposal for an zero-ioctl (best case) DMA transfer mechanism.
			</para>
			
			<para>
			Let's call it 'kernel ringbuffers'.  The premise is to replace the
			calls to the 'fire-vertex-buffer' ioctl with code to write to a
			client-private mapping shared by the kernel (like the current SAREA,
			but for each client).
			</para>
			
			<para>
			Starting from the beginning:
			</para>
			
			<itemizedlist>
				<listitem>
					<para>
					Each client has a private piece of AGP memory, into which it will
					put secure commands (typically vertices and texture data).  The client
					may expand or shrink this region according to load.
					</para>
				</listitem>
				
				<listitem>
					<para>
					Each client has a shared user/kernel region of cached memory.
					(Per-context SAREA).  This is managed like a ring, with head and tail
					pointers.
					</para>
				</listitem>
				
				<listitem>
					<para>
					The client emits vertices to AGP memory (as it currently does with
					DMA buffers).
					</para>
				</listitem>
				
				<listitem>
					<para>
					When a state change, clear, swap, flush, or other event occurs, the
					client:
					</para>
					
					<itemizedlist>
						<listitem>
							<para>
							Grabs the hardware lock.
							</para>
						</listitem>
						
						<listitem>
							<para>
							Re-emits any invalidated state to the head of the ring.
							</para>
						</listitem>
						
						<listitem>
							<para>
							Emits a command to fire the portion of AGP space as vertices.
							</para>
						</listitem>
						
						<listitem>
							<para>
							Updates the head pointer in the ring.
							</para>
						</listitem>
						
						<listitem>
							<para>
							Releases the lock.
							</para>
						</listitem>
					</itemizedlist>
				</listitem>
				
				<listitem>
					<para>
					The kernel is responsible for processing all of the rings.  Several
					events might cause the kernel to examine active rings for commands to
					be dispatched:
					</para>
					
					<itemizedlist>
						<listitem>
							<para>
							A flush ioctl. (Called by impatient clients)
							</para>
						</listitem>
						
						<listitem>
							<para>
							A periodic timer. (If this is low overhead?)
							</para>
						</listitem>
						
						<listitem>
							<para>
							An interrupt previously emitted by the kernel. (If timers	don't work)
							</para>
						</listitem>
					</itemizedlist>
				</listitem>
			</itemizedlist>
			
			<para>
			Additionally, for those who've been paying attention, you'll notice
			that some of the assumptions that we use currently to manage hardware
			state between multiple active contexts are broken if client commands
			to hardware aren't executed serially in an order which is knowable to
			the clients.  Otherwise, a client that grabs the heavy lock doesn't
			know what state has been invalidated or textures swapped out by other
			clients.
			</para>
			
			<para>
			This could be solved by keeping per-context state in the kernel and
			implementing a proper texture manager.  That's something we need to do
			anyway, but it's not a requirement for this mechanism to work.
			</para>
			
			<para>
			Instead, force the kernel to fire all outstanding commands on client
			ringbuffers whenever the heavyweight lock changes hands.  This
			provides the same serialized semantics as the current mechanism, and
			also simplifies the kernel's task as it knows that only a single
			context has an active ring buffer (the one last to hold the lock).
			</para>
			
			<para>
			An additional mechanism is required to allow clients to know which
			pieces of their AGP buffer is pending execution by the hardware, and
			which pieces of the buffer are available to be reused.  This is also
			exactly what NV_vertex_array_range requires.
			</para>
		</sect3>
	</sect2>
    
	<sect2 id="ati">
		<title>ATI Cards</title>
		
		<sect3 id="ati-devrel">
			<title>How do I obtain specifications to the ATI cards?</title>

			<para>
			Please read this <link linkend="nda">section</link> before you consider applying.
			</para>
		</sect3>

		<sect3 id="ati-tv">
			<title>Is there support for the video and TV playback features of cards made by ATI?</title>

			<para>
			Check the 
			<ulink url="http://gatos.sourceforge.net/">
				GATOS
			</ulink>
			project for that.
			</para>
		</sect3>
	
		<sect3 id="Mach64">
			<title>Mach64 based cards</title>
		
			<sect4 id="mach64-status">
				<title>What's the status of mach64 branch?</title>
				
				<para>
				Leif Delgass has a page describing the current status of the mach64 branch 
				<ulink url="http://www.retinalburn.net/linux/dri_status.html">here</ulink>.
				He also has a <ulink url="http://www.retinalburn.net/linux/test_results.html">page</ulink> 
				has links with the results of OpenGL conformance and performance tests on the mach64 branch.
				</para>
			</sect4>
			
			<sect4 id="mach64-build">
				<title>How do I build the mach64 branch?</title>
				
				<para>
				Follow the steps described in the Leif Delgass' 
				<ulink url="http://www.retinalburn.net/linux/dri_HOWTO.html">Compiling the mach64 branch of DRI mini-HOWTO</ulink>
				.
				</para>
			</sect4>

			<sect4 id="mach64-info">
				<title>Where can I get documentation about mach64 chipset?</title>
				
				<para>
				Take a look at the code, the list archives and the DRI documentation on
				its homepage (it's a little stale, but a good starting point).
				</para>
				
				<para>
				We are also
				using the driver from the <ulink url="http://utah-glx.sf.net">Utah-GLX</ulink> project as a guide, so you might want
				to check that out.  
				</para>
				
				<para>
				Many have documentation from ATI as well, you can apply to their <link linkend="ati-devrel">developer program</link> for documentation. 
				</para>
			</sect4>
		</sect3>
	</sect2>

	<sect2 id="tdfx">
		<title>3DFX</title>

		<sect3 id="tdfx-specs">
			<title>How do I obtain specifications to the 3DFX cards?</title>

			<para>
			You can get them <ulink url="http://www.medex.hu/~danthe/tdfx/">here</ulink>.
			</para>
		</sect3>
		
		<sect3>
			<title>What's the relationship between Glide and DRI?</title>
			
			<para>
			Right now the picture looks like this:
			</para>
			
			<para>
				  Client -> OpenGL/GLX -> Glide as HAL (DRI) -> hw
			</para>
			
			<para>
			In this layout the Glide(DRI) is really a hardware abstraction
			layer. The only API exposed it OpenGL and Glide(DRI) only works with
			OpenGL. It isn't useful by itself.
			</para>
			
			<para>
			There are a few Glide only games. 3dfx would like to see those work. So
			the current solution, shown above, doesn't work since the Glide API
			isn't available. Instead we need:
			</para>
			
			<para>
				  Client -> Glide as API (DRI) -> hw
			</para>
			
			<para>
			Right now Mesa does a bunch of the DRI work, and then hands that data
			down to Glide. Also Mesa does all the locking of the hardware. If we're
			going to remove Mesa, then Glide now has to do the DRI work, and we have
			to do something about the locking.
			</para>
			
			<para>
			The solution is actually a bit more complicated. Glide wants to use all
			the memory as well. We don't want the X server to draw at all.  Glide
			will turn off drawing in the X server and grab the lock and never let it
			go. That way no other 3D client can start up and the X server can still
			process keyboard events and such for you. When the Glide app goes away
			we just force a big refresh event for the whole screen.
			</para>
			
			<para>
			I hope that explains it. We're really not trying to encourage people to
			use the Glide API, it is just to allow those existing games to run. We
			really want people to use OpenGL directly.
			</para>
			
			<para>
			Another interesting project that a few people have discussed is removing
			Glide from the picture at all. Just let Mesa send the actual commands to
			the hardware. That's the way most of our drivers were written. It would
			simplify the install process (you don't need Glide separately) and it
			might improve performance a bit, and since we're only doing this for one
			type of hardware (Voodoo3+) Glide isn't doing that much as a hardware
			abstraction layer. It's some work. There's about 50 calls from Glide
			we use and those aren't simple, but it might be a good project for a few
			people to tackle.
			</para>
		</sect3>
	</sect2>

	<sect2 id="s3">
		<title>S3</title>
		
		<sect3 id="S3TC">			
			<title>
			Are there plans to enable the S3TC extension on any of the cards 
			that currently support it?
			</title>
			
			<para>
			There's not a lot we can do with S3TC because of S3's patent/license
			restrictions.
			</para>
			
			<para>
			Normally, OpenGL implementations would do software compression of
			textures and then send them to the board. The patent seems to prevent
			that, so we're staying away from it.
			</para>
			
			<para>
			If an application has compressed texture (they compressed them
			themselves or compressed them offline) we can download the compressed
			texture to the board. Unfortunately, that's of little use since most
			applications don't work that way.
			</para>
		</sect3>

		<sect3 id="savage">
			<title>Savage</title>

			<sect4>
				<title>Are there any plans to support the Savage chips?</title>

				<para>
				Yes. You can read the  <ulink url="http://www.geocrawler.com/archives/3/680/2002/10/0/10033439/">original announcement</ulink>.
				</para>
				
			</sect4>

			<sect4>
				<title>What's the status of the Savage driver?</title>

				<para>
				At this point work is still being done to make the 2D driver DRI aware. See the 
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/programs/Xserver/hw/xfree86/drivers/savage/?only_with_tag=savage-0-0-1-branch">Savage DDX driver on CVS</ulink> and the preliminary <ulink url="http://dri.sourceforge.net/doc/howto/ddx.html">DDX chapter of the DRI Driver HOWTO</ulink>.
				</para>
				
				<para>
				<filename>savage_dri.c</filename> is	still needing several functions. i've been basically copy &amp; pasting from the other drivers (especially Radeon, which is one of the most recent)	to fill in the void.
				</para>
			</sect4>
			  
			<sect4>
				<title>How can I help?</title>

				<para>
				Making the DDX DRI-aware doesn't require a very deep knowledge is a
				matter of mostly copy &amp; pasting from other drivers. Bootstrapping a DRM
				kernel module is also easy - see for example the 3DFX one. Both these
				things could be done by a newbie, allowing the developers to
				concentrate on the more demanding Mesa driver.
				</para>
			</sect4>
		</sect3>
	</sect2>
</sect1>

<!-- vim: set ai ts=2 sw=2 noet: -->
@