Okay, even though I promised to myself to not reply back, I will because I respect some of the the DRI developers and what they have to say. After all when my OpenGL apps run on Linux, they use their codes!
So I put a few hours worth of time into this email. If the DRI is of concern to you, please read. I will quote certain portions and who wrote them and answer below. The answered posts in order: 1) David Dawes (sent only to me, not the list) 2) Brian Paul 3) Kevin E Martin 4) Lincoln, Michael C 5) Daryll Strauss 6) John Utz 7) David Johnson 8) Gareth Hughes 9) David Bronaugh A) Ian D Romanick B) Jens Owen C) Michael -------------------------------------------------------------------------- NO RESPECT: >-----Quoted Message----- >From: David Dawes <[EMAIL PROTECTED]> >Sent: Thu, 17 Jan 2002 11:30:04 -0500 >To: [EMAIL PROTECTED] >Subject: Re: [Dri-devel] DRM/DRI porting guide? > >On Thu, Jan 17, 2002 at 02:40:15AM -0800, [EMAIL PROTECTED] wrote: >> >>Okay, sorry, I just had to laugh. Not your fault, I admit that. You >>are as innocent as I used to be. > >I don't know why you expect a free ride. Nobody gave me one when >I started learning about X 10 years ago. The things you're talking >about weren't there to make it easy for me. I had to do it the >hard way, so I have no sympathy for whiners like you who want it >given to them on a plate. Your rant is basically a bunch of excuses >for your own inadequacy. You won't get anywhere until you stop making >excuses. > >David David, it's been a while that I have learned that age doesn't go hand in hand with wisdom (wisdom != smartness in my book). So no suprises from you. All I have to say is that I really didn't expect these kinds of comments from you. Heck, you even look smart on your tungstengraphics.com picture! Now, since you brought it to a personal level I will answer in a personal level: You obviously never read past those first 2 lines. If you read further you would have realized that I wrote very clearly that I did NOT want a free ride. I had spent many hours on code writing, reading and would even more. I stated that clearly and seriously, and if you don't believe it, keep it to your self. My discussion was serious and not a petty child dispute. As far as documentation when you started learning X 10 years ago, this is what I have to say: 1) only 10 years ago? I thought you found XFree86, but what about before? X11 was already out there, no ? No matter... 2) How many X-related man pages are there? Include XFree86's, the original MIT pages, Sun's SGI's etc etc etc. Tons I have seen. 3) How many X-related books have you seen on bookselves? Plenty, right? Seen any DRI ? None! As for sympathy for whiners: as you are so blind in your own hubris I will clarify it for you: today's newbies (me, others), are YOUR future. We are the ones that will carry your project if you get hit by a bus. Do you care enough about your projects? Then think about us "whiners" who actually want to help, because we BELIEVE in your cause! Remember, there's always the Dark Side, and we didn't align with it yet. Finally as far as inadequacy of myself and how far I will go: you really blew it there buddy. How do you know my adequacy when you don't even know me? I am self-actualized enough to admit that I am inadequate at tackling the giant project alone, but that really speaks no more about my coding abilities or adequacy (or not) in other projects. Apart from me stating multiple times that I am quite experienced in related projects, and even stating some areas of knowledge, you still think you can judge someone's abilities from miles apart? Yes, I know the typical reply: you haven't seen any of my code in your projects, but I surely haven't seen any of your code in my projects either. Think about this. Once again: I never said, and will not say that I "own you in coding skills". In fact I really could care less. What I do want to state is: I wanted to be able to code with you guys on the DRI. Once again: most DRI-wanna-be developers are NOT fruitcakes, but have decent programming experiences, just NOT with DRI. What's so hard to understand about that? Please next time read the entire post, and think about what you write. It was clearly not a personal attack on you or any DRI developers. On the contrary I clearly stated how much repsect I have for the work you guys have put in (in most areas, but certainly not in the documentation area). Next time post your opinions on the list too. PS. I still want to thank you for your work on XFree86. Much appreciated. -------------------------------------------------------------------------- RESPECT: From: Brian Paul <[EMAIL PROTECTED]> Date: 2002-01-17 14:58:01 >OK, I'm going to waste some of your time - I don't have any new DRI docs >for you. no problems, coz I'd like to hear what you have to say >Even before VA Linux laid-off everyone we were losing momentum on the >DRI project because the engineers had to work on other projects that >generated revenue. After everyone was laid-off we all went in different Understood, and making a living is primary for people. That's why I "whine" for documentation though, because it's the only thing that can keep the project alive, because unfortunate life situations like the above can happen to anyone (the typical "hit by bus" scenario) >I have time to read the list, but really nothing more. My spare time >is occupied with developing Mesa. I often wish there were more hours in >a day so I could do more, but there aren't and I can't. Back when we were >actively writing the DRI drivers we were working our asses off. Gareth, >for >example, was routinely working 80+ hours per week on this stuff. Understood and believed. That is why I said we appreciate what you have done and the post was not intended to downplay all this, but to raise awareness for an extermely important deficiency in the project. Heck, without the uber-work you guys have put in the project our 3D apps would not be spinning around right this moment. No doubts there. >We thought it was more important to invest our time in the drivers and >>infrastructure code than writing/updating design documents. The DRI is >very >complicated and takes a lot of time to understand. We didn't try >to make it complicated - that's just the reality of it. Yes, your decision is/was evident. It even made sense back then. It's the reason why we had so many working drivers so early. But, right now, looking at how things have gone, I can only say: this decision is wrong today. Design and implementation of drivers is not primary. Documentation for the guaranteed longevity of the project is primary and then driver implementation. This should be clearly evident with the tremendous DRI developer attrition that's visible today. Not only visible, but stated cleary by you yourself. >The DRI isn't dead though. Keith and Alan have been working on >the mesa-4-0-branch to bring Mesa 4.0 (OpenGL 1.3) to the DRI. Glad to hear. And I trust your words that it is so. >We at Tungsten Graphics have hopes to develop new DRI drivers. >But the top priority is to do the work that pays our bills. I understand this fully. You have a life to live and it's yours. And I have no right to force things upon you. That's why I am urging, not forcing. Plus I can't force, coz if I could, we'd have already tons of docs :) But there are solutions. I will talk about this in the further posts that some other new developers have posted. >PS: We should probably give CVS-write privilege to more people who >want to contribute patches and such. I think that's a bottleneck right >now. Anyone? I disagree with this hear. From my new developer point of view the bottleneck is new developers. I don't care if you give me CVS access tonight (i don't want it). I have nothing to submit. I want docs to help me going. Then I will have something to submit. I would further urge other new developers/wanna-be's to state their opinion on this. Is CVS access key, or docs ? -------------------------------------------------------------------------- RESPECT: From: Kevin E Martin <[EMAIL PROTECTED]> Date: 2002-01-17 16:17:51 >> design documents. The DRI is very complicated and takes a lot of >> time to understand. We didn't try to make it complicated - that's >> just the reality of it. > >Exactly. In fact, Brian (and others) did some great work simplifying >the original code that we developed. Kevin, I just want to clarify that I have not personally heard any new developers asking for the project to be simplified. I know I haven't. Also, in my original post I did clearly state of our acceptance of this very ambitious project. Because as anyone having read both the PI docs and the SGI Direct Rendering docs and other related docs, realizes that the DRI is very ambitious! It's not a hack. It's the real deal of allowing cooperating access to a finite set of resources and doing it "The Right Way". >For those that have the time right now and the technical background, >delve into the code and write up what you find. If you post your >writeups here, then the DRI community that has built up and hopefully >some of the original developers (time permitting) can help clarify and >correct the docs. The DRI, Mesa and XFree86 are not simple pieces of >code, but perhaps this is a way to help get people over the learning >curve required to understand and then contribute code. It is certainly a way. But I believe that it's very similar to a "reverse engineering" project, with the exception that the creators of it _are_ available. The information IS out there. And it seems quite stupid that when they are available you set about to reinvent the wheel. So you turn and say: they are busy 24/7. Well, issue can be worked on. Look further down for related replies from other new developers and my input. -------------------------------------------------------------------------- From: "Lincoln, Michael C" <[EMAIL PROTECTED]> Date: 2002-01-17 16:26:08 >Is the size/complexity of a project that can be attempted with open >source fundamentally limited? I really hope not, but let me tell you: you (anyone) surely will NEVER know for this projects. Why ? Because we haven't even "tried". When there's no effort to follow even a standard project methodology (take for example the stuff in computer science class: pre-design docs, design-docs, testing-docs, maintanance-docs, etc etc), then how will we ever know? Note: I am not proposing something as rigorous (and wasteful at times) as what they teach in CS classes, but even some serious attempt to break from the "hack stage" (code only) to a serious "project stage" (code and docs). >Would better documentation help or is the learning curve just too steep >for most would-be DRI hackers? I don't even think that's a proper question. There's no project in my opinion made by humans that other humans cannot comprehend. Surely maybe only 1% of would-be developers will, but at least that's 1% BTW, in the case of the DRI my opinion is that anyone with some fundamental C and hardware experience, and some basic X11/GL/kernel experience can work on the project. >If better doc's would help, who has the knowledge and time (or funding) >to do it? Knowledge: original DRI creators Time: the typical answer is no one, but this can be worked on (look further down) Funding: no one it seems :( -------------------------------------------------------------------------- RESPECT: Subject: Re: [Dri-devel] DRM/DRI porting guide? From: Daryll Strauss <[EMAIL PROTECTED]> >Now I'm going to turn this around a bit. You've already seen the answers >from most of us. We're still here, but we're busy with other projects, >and our time is limited. We're all still reading the list and posting >when it seems appropriate. Yes. Personally I didn't state non-availability of DRI developers. But I did state that not many did answer quite a few questions which were especially targetted at helping create some kind of basic devel docs. To my questions I did get replies, but very few, and incomplete. Further, I have seen many other people ask devel. related issues gone un-answered. Yes, yes, I know: busy. That's why documentation is so important. Saves you guys from answering stuff already answered. >It's hard work writing docs. It's not a lot of fun (particularly for a >developer) to spend time writing docs. Hard writing "proper" docs I will accept. Writing a Readme or something alike to Utah-GLX docs is not Daryll. Seriously, with the typing speed that most of us programmers have, I bet anyone who knows their subject can bang out a 5 page doc in under one day. It's a matter of scheduling it. Will talk about this further down. As for not fun to writing docs, always think about it this way: guarantees that I won't be bugged every day about simple stuff :) >It is much easier to answer questions than it is to write docs. If >someone takes the initiative to do some digging and ask questions we're >much more likely to respond? Why? Because the scope they're asking for >is more limited. Because they've shown their invested in the >project. You'll find that when you work on open source projects that >lots of people will ask you to give of your time and very few will >contribute on their own. I agree on the idea of "limiting the scope". But I disagree on thinking automatically just because someone is asking a question has not invested time. When you see a person lurking on the lists and asking questions, obviously they have spent time. Even if not lurking, just seeing their question will give you a good understanding of how much time they have spent. I mean, if they ask what you already know is in the Readme or FAQ, then you know they are lazy. Once again though, these are the exact issues that writing docs will help prevent and never think about. With Frank's DRI site rework I think many of these issues were solved. Anyone asking stuff and being lazy is told: dri.sourceforge.net Done. Not the same when it comes to devel related questions. >A good starting point would be to dig through the archives of this list >and collect what's there. It would have a lot of holes, but it would be >a good place to start. I realize it's a pain in the ass, but it's a >start. Has anyone done that? No. To me this defies logic. I have done it in the past, but the sheer volume of the archives, plus the code, plus the number of holes that would be left open is so big that it comes down to: reinventing the wheel == stupid, or the wheel won't be round but square. On the contrary I see this as a good method when searching for bugs or seeing if someone else had a particular issue with some hardware. I always do this with DRI, kernel, etc. But documenting one of the most imporatant OSS projects this way? It's madness Daryll. Especially when the DRI guys haven't ben hit by a bus yet!! (thank god. yeah I know, you've been hit by the time-bus) Another issue I have with the above methodoly is this: it's like a hash table. You get info surely on many subjects, but this info is not ordered. So, if you want to start a devel doc for DRI, you will have a lot of holes all over a place and in no order. So even if there are lots of docs (size wise), it doesn't guarantee that the fundamental stuff (how to start on a driver, or the basics) will be there !! So again: waste of time. A new developer wants Chapter 1, Chapter 2 etc etc. Doesn't care to have Chapter 13 and Chapter 10 and no Chapter 1. >Another reasonable complaint is that you need to download too much code >and it takes too long to build all of X. Not everyone has fast machines >and lots of bandwidth. Since the client side OpenGL doesn't change much, Personally I don't regard this as big a problem as docs. At home I have a 56k modem still and have managed with cheapo Celerons to do it. I don't see others being much worse off. Finally with CVS you solve the "re-download the entire tree" problem. >wouldn't it be nice to have a way to compile that separately, so it is >smaller and faster? Yep. Someone do it. It would be a good idea to do this. However personally I don't see it as big a problem as docs, that's why I didn't mention it. >I know I've written this same piece to the list multiple times, but in >order to be more proactive, here's a place to start. All OpenGL drivers >are made up of 3 parts: > >A DRI aware 2D driver which lives in > xc/programs/Xserver/hw/xfree86/drivers/... I have never seen all three paths in the same email, but have seen the pieces at various times, unfortunately never got this clear an answer when I asked in my most official attempt to develop some kinda simple devel guide .. Anyways, I am glad it's already starting to be useful to people (John Utz) >I've given a couple presentations on the DRI, so maybe I can find one of >those to post as well. See what I am talking about? Reinventing the wheel, while we know the wheel is out there... I know you must have been busy as hell and you forgot about it, but we _really_ wanted these presentations :) >people. My stock answer when asked is that you should submit a patch or >two before we give access. Now one has. I agree with this policy. I don't see a reason to change it. Once again, I don't believe CVS access is the bottleneck. Oh and a big "Duh" on the "Now one has." part. -------------------------------------------------------------------------- From: John Utz <[EMAIL PROTECTED]> Date: 2002-01-17 18:37:15 >but i have been lurking on this list for the last year ( which is more of >an investment than you might think! ) Yes, some people forget that even new-DRI developers have lives, and other projects as well... >and it appears that adoniz makes some valid points, tho perhaps in an >overly >vigourous fashion. :-) I didn't mean to be mean spirited. Honestly. I care about the DRI, otherwise I wouldn't spend all this time writing about it. Does this make sense to people? I hope it does. > This is probably the most technically complex one in >existence - a good graphics card is effectively another computer. I don't believe so myself. It certainly at the top, but if you think about the kernel and it working with not 10 grafix chips, but hundreds of chips of various kinds (DSP's, grafix, serial, network, hard drive, sync, async, audio, etc etc), then it's certainly more comples. Memory management? Kernel does it. Balancing? Does it too. Locking, various architectures, even endian issues. Does it all. Still, this project is complex enough, due to it sitting upon other complex projects as stated before: kernel + X11 + Mesa + GLX >no matter, i'll go src spelunking and take a few notes, and maybe bake up >a few perl scripts to generate some annotation. that way i can track what >changes and add it to the notes. I don't mean to stop you or anything, but what's the point? When one doesn't know what the function is _intended_ to do, what good is it if he writes up what the function _does do_ ? In fact that's a major source of programming errors: confusion about the design. But guess who are the only people who know what the function was _intended to do_ ? That's where we gotta get docs from. If I knew the intention, then I could go and even fix the functions that don't adhere, coz afterall the code is there. Of course not all functions need to have stated intentions. But for the DRI many do, coz I surely did feel that when I kept on asking myself after staring at the code dozens of times: wtf is this function trying to do? >so, adoniz, you alluded to have written a stub. care to share? I called it a mini driver for lack of better words. Basically it was just code to mmap() the video memory buffer and allow IO port access so I can start fiddling with the card. Then had calls to obviously start the card going, send commands to it, and have it draw on screen. Then I decided to design a miniGL a-like interface so it could make my transition to the DRI easier, once I had the eye-opening experience to find some decent DRI docs and understand where to even plugin my cardXXX_draw_tri() cardXXX_draw_tri_strip() etc etc. All this stopped of course when I realized that I wasn't gonna get docs, and certainly had better things to do than re-invent the wheel. I will look for the odd pieces and if I still have them will email u .. -------------------------------------------------------------------------- From: "David Johnson" <[EMAIL PROTECTED]> Date: 2002-01-17 20:01:14 >The problem is that DRI development has never reached critical mass in >the open source world. I agree. It's a tough one, no doubt. Plus a DRI developer has to like working with grafix, hardware, kernel, and X11 >There was a time when there were quite a few developers working on DRI >related >projects a PI or VA but much of the design discussions were >private and people couldn't eaves drop on the 'experts'. My opinion as well. >A combination of eaves dropping and browsing through code is how many >people get up to speed on open source projects. This didn't happen with >DRI so the same experts of 2 years ago are the same experts today except >that many of those experts are now on to other projects. Yep. >...quickly results in a developer looking for more interesting projects. > Every month someone comes along the DRI mailing list, mentions that they >are interested in doing work, and then shortly later dissappears. Every >time that happens that is another developer gone on to another project >that interests them because they couldn't get over the learning curve and >another >developer lost to the DRI project. Exactly what I saw too. >The solution is that we need a way to get the information flowing between >the handful of DRI experts and the people who want to become DRI experts. YES. TO AVOID RE-INVENTING THE GODDAMN WHEEL. The information IS there. That's what I am arguing about. Why re-invent it when it is already there. Yes time is the evil bastard that's blocking it, but we can work on that. But it takes work on both sides. >...DRI will reach critical mass and the experts can spend their time >working on the complex issues. Exactly. Documentation will FREE the DRI core developers. Give them more time to do what they want instead of answer same stuff over and over. >So, the question is how to we get that process going. As a suggestion, >maybe a weekly IRC meeting would help where new developers can ask the >experts, and >each other, questions about DRI, XFree or 3D graphics. >I am sure it would be much easier for Darryl, Paul, or any of the other >DRI experts to allocate an hour or so a week to participate in an IRC >chat as opposed to monitoring and answering mailing list messages. >It would allow the new developers to more quickly get answers to their >questions. >Also, the IRC logs could be posted on the DRI web site. It's not a bad idea. I had something in similar lines that goes like this: Instead of an IRC session, allocate 1 day a week, where a core DRI developer will tackle one major DRI component of function and spend 1 hour max documenting it. I have not fully thought this out, so this is a rough draft: First we need to make a complete list of functions and modules necessary to be documented. Then, we can have them assigned to the DRI developers that can answer them best. Then one day of the week (weekend?) have each developer post on the list which function he will document before he starts (ex: I am developer X. I am starting now to document functionXXX). Then he goes offline or whatever. Then when he's done with the appropriate documentation and has time left, goes on to another function. If time has past (1 hour limit), then he completes the one started as best as possible. At the end of the session he posts on the list. Other developers can further look and respond. Final version with corrections is collected by us and added to the developer docs on the dri.sourceforge.net page (and can further be PDF'ed, HTMLized, etc etc) and marked off the complete list of functions/modules that need to be documented. The time variable and number of functions can of course be altered. I picked one hour, maybe 30mins is better. I don't know. Like I said, just an idea. But the idea is to force this to happen, that's why each developer with assigned tasks has to post on the list that he's doing it. Further if time permits we can pump out more work (if docu of first function is done and time left still, move on to the next one). The above would be suceptible to periodical changes as the DRI matures. Of course this by itself is not enough. We still need someone to write a good 10-40 (maybe more?) page doc on how to get someone started with writing a driver. What modules need to be written. What functions and files need to be touched. What is the bare minimum of necessary functionality that needs to be completed for the driver to "boot up". This would not be as suceptible to periodical changes. AKA it would not change so often (maybe a one-time deal? if the DRI design has stabilized internally) >New developers are far more likely to read an IRC log than scan through >months and >months of mailing list archives. Honestly, I suspect no one >ever reads mailing lists archives to get general information. I disagree here. I rather read mailing lists archives for general info rather then IRC logs. Information is compartmentalized in emails, while scattered with random interjections on IRC logs. Please read this link very carefully, and see if it makes sense to you. I agree with Ingo Molnar (towards the end of the posts). In fact I urge everyone interested in the IRC vs Email/Achive issue. http://kt.zork.net/kernel-traffic/kt20020107_149.html#1 -------------------------------------------------------------------------- From: Gareth Hughes <[EMAIL PROTECTED]> Date: 2002-01-17 22:15:32 >80? Huh, that was a light week :-) Heh, I remember and I agree. We don't forget Utah-GLX either... >Regarding documentation, and the comparisons to other large projects >like the Linux kernel, think back to what it must have been like in >the early 90s. Do you think there was anywhere near the amount of >documentation there is now on kernel development? No it's not comparable. The reason why is because the kernel code in the early 90's was WAY simpler than the DRI code in early 2000's (well you know what I mean, when DRI started). Why? Kernel was just started back then. If I recall correctly the kernel codebase in the early 90's was in the megabyte region. Certainly less than 10. DRI didn't just start by itself. It started WITH kernel module and X11 code. Heck, with X11 and kernel code base you have over 100 megs of code. That ain't comparable Gareth. Sorry. >Writing a whole driver is a *serious* contribution. I'd say it took >me about a year of working with various drivers, and watching people >like Keith and Brian do their magic, before I felt comfortable in my >level of understanding of how the Mesa-based DRI drivers worked and >how all the pieces fit together. You really are kidding yourself if you >think you'll be able to pick this up in a matter of weeks. None of us have ever mentioned needing a few weeks. 56 weeks maybe, but not less. Most of us who have asked for documentation also been around the lists since early DRI days. Finally, going back to Utah-GLX, certainly not the monster that DRI is, writing a driver from scratch (because it was so easy to base your code off the other drivers, 3-4 files and that's it), was possible in a matter of weeks. Recall the S3 and SiS drivers by what's his name, I forget right now.. Heck, I only with DRI code layout was similar to Utah-GLX in some cases. But of course DRI is much bigger than Utah-GLX. I know. But I can still wish :) >Not that this should discourage you from working on the DRI or Mesa... It's already been done ... >While we're making comparisons with the Linux kernel, you need to think >in terms of porting the kernel to a new architecture, or maintaining one >of the core bits like the VM, networking, VFS etc, instead of a character >device >driver for the real-time clock, say, when you think about writing >a solid, fully-featured driver for a modern 3D graphics processor. Yes and no. Depends. The DRI is supposed to be infrastructure and the 3D driver a plugin for it. Similarly the kernel is the unfrastructure and a driver (be it, grafix, audio, serial, network, etc) is a plugin. Of course the DRI does have to deal with "new architecture" issues as XFree86 is also architecture independent, but so does the kernel. Either way, I was not trying to make a direct comparison on the ease of writing drivers. Some areas are comparable though. >To continue the comparisons with the kernel, how much documentation >do you think there is on the bleeding-edge work being done by the >core developers? Is there a "How To Hack On The New 2.4.10 VM" >document anywhere? Or "Ten Easy Steps For Writing Your Own >Kernel-Based HTTP Server"? "DaveM's Guide To The TCP/IP Stack"? Nice try. First letme say that the VM is something I won't talk about. It's still in the "fuzzy" land of things. But you are right on the other things. There's no docs for writing an HTTP server etc, but don't confuse the following 2 Gareth: 1) Infrastructure documentation 2) driver documentation We are not asking for infrastructure documentation. That's where the bleeding edge stuff that you mention happens. Look further down though for more info on bleeding edge kernel docs. No. We want driver documentation. How to write drivers. I could care less about changing the DRI/DRM internal right now. I just want a generic driver writing doc, or a skeleton model. I know how to draw a triangle, but I don't know where to drop my draw_a_triangle() function! That's what we are talking about. The core DRI developers will take care of the bleeding edge. I do realize that bleeding edge infrastructure docs also affect driver docs, but I would rather have "changing driver docu" any day rather than have "no driver docu". Finally, have you recently: du /usr/src/linux/Documentation ? Even simple text files like that don't exist for the DRI or are seriously outdated (PI docs). I am not even talking about great pieces of writing such as: http://www.tux.org/lkml http://www.kernelnewbies.org (the right side of the page is the FAQ) http://www.linuxdoc.org/LDP/tlk/tlk.html http://www.linuxdoc.org/LDP/khg/HyperNews/get/khg.html http://www.xml.com/ldd/chapter/book/index.html (this is what DRI should have) for more info http://www.kernelnewbies.org/books.php3 and even more http://jungla.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html Okay. We know the kernel has been around since 1991. DRI: Registered: 1999-11-23 12:18 according to sourceforge. 1999-1991 = 8 years longer. But there isn't even a semblance to the amount of docs. By no means is the kernel project the "great bastion of documentation" either, but it's way way way better than the DRI, and AT LEAST those folks are _trying_ to do something about it. Look at this: bleeding edge docs, check this and remember that 2.5.x just started like 2 months ago: http://www.osdl.org/archive/rddunlap/linux-port-25x.html They are trying. Okay, so you say DRI doesn't have the huge developer base of the kernel. I agree, but I mention only this to you: I believe that the DRI is one of those very important projects, just like the kernel, but certainly way more important than let's say my IRC client. So, in this case, why should it be so under-documented. That's my argument. Need _some_ effort at least, which will also help the developer base grow! -------------------------------------------------------------------------- From: David Bronaugh <[EMAIL PROTECTED]> Date: 2002-01-17 23:11:46 >Perhaps a good idea here would be to have some sort of a function >documentation tracking project.. I have been doing a hell of a lot of PHP See above text why function documentation is not necessarily the best approach. To briefly re-iterate: knowing what a function does still doesn't tell you which functions or in what order, the DRI infrastructure requires for a complete driver write. There's no program flow information. The API is still undefined. >comments/information on specific functions, then there could be a list of >links to those functions on another page, so that people could easily >find what others have contributed about that function). As well, I guess >there could >be some sort of general overview section (I'm not clear at >this time how that'd work). What I think would be a great idea and maybe your experience can help in is the following: First we define the conceptual components of the DRI project: DRM DRI 2D DRI 3D Mesa GLX Further break these down into subcomponents. DRI core developers would help here. Further, your code based on these conceptual components will go and weed out the functions that reside in them. Make a tree or graph of them. Interconnectivity and links between them can further convey more information. That way a developer looking at this will get the whole picture of the DRI. Understand how a function in one component relates to another in another, etc. Of course not everything will be evident this way, and infact bad code will be painful to see (confusing), but I think it would help in understanding the overall DRI infrastructure >If someone wants me to do this, I have a machine to host it on, and I'd >be willing to put in the time to develop this. If you do anything, just make sure you coordinate with Frank and the dri.sourceforge.net site, so that the information is centrally available. It will make things easier. -------------------------------------------------------------------------- From: Ian D Romanick <[EMAIL PROTECTED]> Date: 2002-01-17 23:49:34 >This would probably be a great idea, with a little tweaking. One problem >is maintaining useful documentation in, basically, two places. It might >be better to gradually add documentation to the source that could be >automatically be extracted by something like c2man. Then have a page for >each CVS tag, branch, etc. that would nightly extract the documentation >and webify it. Then people could submit comments, like with the FAQ, for >each function. >This has a couple of advantages and a few disadvantages. First, the >disadvantage is that it would be a fair amount more work to get it going. >Changes would need to be made to the source, more scripts would need to >be written, and we would need a system that could be used to extract the >documentation from several trees on (at least) a nightly basis. Ian what you mentioned and also the advantages and disadvantages has been one of the classical issues in computers/CS/programming circles. It's is my opinion that for many programmers is a no-go on the documentation inside the source. I know the majority of the kernel coders subscribe to this ideology and so do I. When I mean doc in the code I mean LOTS of docs in the code. Most do allow/want a few lines before a function, but nothing more than a page. Now for the advantages you mention that the docs go in one place alone for the programmer and thus is easier for them. This is true, but also true if you tell the programmer to write his doc in a file next to his code.c file. Very much in style with a Readme in the same directory for a driver let's say. Now surely some directories contain more than one DRI subcomponent. In this case I think it would be best to make more directories to isolate them, and then it would be a similarly easy step to write the needed documentation in the Readme of that directory. Having a developer write to single text file is no harder than beside the function. What developers don't want to do is write entire books of documentation :)) Finally, in all this documentation talk, let's not forget that: Writing a piece of doc for a function will NOT be adequate as a well written (and a little lengthier than 10 pages) doc on how to start writing a driver based on the DRI infrastructure. Once again some people are arguing for documentation on hacking on the DRI infrastructure, and others (me for example) want documentation on how to write drivers BASED ON the DRI infrastructure. Very different subjects. In theory the latter is only do-able once the DRI infrastructure has stabilized internally. I don't know the full present state of the DRI internally, but seen the 5-6 types of drivers already existing for the DRI I assume it long has reached some decent stabilization, so as to allow some decent driver writing docs. -------------------------------------------------------------------------- RESPECT: From: Jens Owen <[EMAIL PROTECTED]> Date: 2002-01-18 0:57:20 >I agree. Developers are *much* more likely to keep the inline >documentation up to date. Downside is the documentation becomes very >blocky and it's difficult to address over arching concepts. Perhaps a >smaller amount of overview documentation generated from README files in >the source tree could address this. I agree with you Jens. Inline docu is the easiest, but has a big downside, while Readme's are a great compromise between inline and a full book. Please read the comment above this one for what I see as a very important differentiation on documentation (DRI docs vs driver writing docs). -------------------------------------------------------------------------- From: Michael <[EMAIL PROTECTED]> Date: 2002-01-18 4:47:05 >Personally I think the biggest stumbling block to working on dri is >lack of specs for the hardware. I disagree. Here's why: If the specs aren't available then no matter how much DRI docu there is, it doesn't matter. I have specs for hardware not supported by the DRI. What good are they when the DRI itself is undocumented. Think about companies that might release a DRI driver (even binary), but are also faced with the difficult task of writing it for the DRI. Forget about the fact that the Linux 3D market is still miniscule and they simply will abort the project at the very first sign of difficulty (almost non-existant developer base for DRI/3D drivers in Linux. The only ones I know are the core DRI developers (less than a dozen) and a few others (less than half a dozen on the XFree86 side of things most of the time)). >As was said, it's very like porting linux, especially in the sense that >what you write is the x86-ness or the m68k ness, not the http or tcp/ip >stack (well, obviously there are issues and I've oversimplified, but the I disagree partially. Read my reply to Gareth Hughes on this issue. -------------------------------------------------------------------------- The end. Thanks for reading. Good luck to you all. _______________________________________________ Dri-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/dri-devel
