David Johnson wrote: > Could the DRI experts offer some feedback on the relevence and usefullness > of the following documents. Are the reasonably up to date? Are they > moderately up to date? Are they out of date and not extremely useful with > respect to the current DRI artitecture?
I'll throw in my two cents... > 1. Introduction to the Direct Rendering Infrastructure - Brian Paul, August > 2000 > http://dri.sourceforge.net/doc/DRIintro.html Reasonably up to date. Decent Intro. > 2. Dri term glossary. http://dri.sourceforge.net/doc/glossary.html > I suspect this doesn't need to be changed but is there anything that should > be added? Reasonably up to date--except the author, Nathan, no longer works for VALinux->so his e-mail address is invalid. Useful. > 3. Data flow diagram > http://dri.sourceforge.net/doc/data_flow.jpg Very high level. Good for someone brand new to the concept of direct rendering--we'd use this at trade shows to explain what we are doing at a very high level. > 4. Control flow diagram > http://dri.sourceforge.net/doc/control_flow.jpg This is moderately up to date (and moderately out of date). I find this very useful as a module map of where all the pieces go and how they fit into the big picture. So, I guess this is the "big picture" :-) That's why there is a big version at http://dri.sourceforge.net/doc/control_flow_poster.jpg. A developer interested in writing a new driver should focus on the Red Boxes. Those are the pieces that need to be recreated for each new device. Items that are out of date include: - The modules in the kernel for the DRM. There is no layering and there is not generic driver. There should be a red box labeled "DRM Driver". - The layers at the top of the "OpenGL Compatabile Core Rendering Library" between a 3D client side driver and the application. - Need to deemphasize the MMIO path and make the DMA path easier to follow because all drivers since 3Dfx have used that path. - Consider adding the agp modules to this diagram. > 5. A Multipipe Direct Rendering Artitecture for 3D. Jens Owen, Kevin E. > Martin. September 1998 > http://dri.sourceforge.net/doc/design_high_level.html Surprisingly, these is moderately up to date. I don't recommend this for somebody wanting to write their first driver--rather, it's a high level design document written before we implemented any of the DRI. It helped us focus on the design tradeoffs we wanted to make. This is somewhat useful to anyone wanting to change the DRI framework. It gives a good idea of our original design goals. > 6. Direct Rendering Infrastructure, Low-Level Design Document. > Kevin E. Martin, Rickard E. Faith, Jens Owen, Allen Akin > http://dri.sourceforge.net/doc/design_low_level.html This is woefully out of date, and not needed by developers tackling their first driver. This *might* have some value for developers looking to push the infrastructure envelope; however, I think the following docs are more useful... > 7. The Direct Rendering Manager: Kernel Suport for the Direct Rendering > Infrastrucure. Rickard E. Faith > http://dri.sourceforge.net/doc/design_high_level.html You've got the wrong link here. It should be http://dri.sourceforge.net/doc/drm_low_level.html Although this hasn't been touched since the DRM library was first implemented, this is still a moderately up to date document. It does a decent job of documenting the DRMLib interface (The yellow box labeled "DRMLib" in the control flow diagram). Since the DRMLib interface is used by and supported by a device specific driver suite--it is good reading for first time driver developers. Items that are out of date: - Layering of DRM support, no more layers or generic driver; we now have DRM templates developed by Gareth. - Security Mechanism is slightly different. The flow of approval was reversed--but I don't remember the exact details. - This interface has been extended for some drivers...driver specific IOCTL's added. > 8. Hardware Locking for the Direct Rendering Infrastructure. Rickard E. > Faith, Jens Owen, Kevin E. Martin > http://dri.sourceforge.net/doc/hardware_locking_low_level.html This document is in decent shape. However, we don't use hardware locking very much for DMA based drivers; and it's really a infrastructure design justification. Not recommended for 1st time driver writers; better for developer wanting to extend the infrastructure and needing a low overhead lock. > 9. A Security Analysis of the Direct Rendering Infrastructure. Rickard E. > Faith, Kevin E. Martin > http://dri.sourceforge.net/doc/security_low_level.html Out of date in that the mechanisms have changed. Also, not very relavant to 1st time driver writer. > 10. DRI Extension for supporting Direct Rendering Protocol Specification. > Jens Owen, Kevin Martin > http://dri.sourceforge.net/doc/dri_extensions_low_level.txt Reasonably up to date--but only useful to somebody wanting to change the infrastructure. A document describing the API in the DDX drivers that support this extension would be much more useful to the driver developer. Specifically the API defined by the header xc/programs/Xserver/GL/dri/dri.h. This interface is supported by a DDX driver in the X Server and is what makes a DDX driver into a "DRI aware DDX Driver"; the red box in the middle of the control flow diagram. > I believe those are all the important developer and design documents on the > DRI website. Do any others exist anywhere that might help developers? Not that I can think of. > I think the first step might be to clean up the high level design documents > so new developers can quickly see how all the pieces of DRI fit together and > how they are interdependent on each other as well as with XFree86, Mesa and > the kernel. Sounds reasonable. > From there we can develop more detailed documentation on each > part of DRI and the major functions used in each part (this documentation > can be done through extracing in code documentation as others have > suggested). When all is done I would like to have it so that if, for > instance, someone is having a problem getting AGP to work with a Graphics > card ABC and motherboard XYZ and want to fix it they can quickly browse over > the high level documentation which will explain to them the DRI artitecture > and point them to the appropriate place(s) in the source code where AGP > related stuff is handled. I like your intent--I hope it's not over simplified. > Again, I don't think we can demand that Daryll, Paul, Jens, and the other > DRI experts sit down and write documentation or spend 8 hours a week in IRC > chats but if we can get them to point out what is wrong with current > documentation and share some of their knowledge with the rest of us > hopefully the rest of us can take the ball and run with it. I hope my two cents will help. Regards, Jens -- /\ Jens Owen / \/\ _ [EMAIL PROTECTED] / \ \ \ Steamboat Springs, Colorado _______________________________________________ Dri-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/dri-devel
