Announcement

Collapse
No announcement yet.

AMD Documentation Drop Next Week

Collapse
X
  • Filter
  • Time
  • Show
Clear All
new posts

  • #31
    Originally posted by bridgman View Post
    No argument there. Only question is whether the documentation should be standalone or embedded in the code. My experience has been that really well documented code is more useful than separate doc & code, but that's just personal experience not fact.
    I'm not a programmer, but I think that the code should be commented by the programmer that wrote it with the purpose of clarifying the code, and there should also be a separately written documentation in English with the purpose of explaining why drivers are written and structured the way they are.

    This should server two purposes. The code will function as an example of proper structure and coding ethics, (which will be explained in the comments) and the documentation should lay down the theory. It's just like school, you have theory classes and lab classes. The theory classes explain the why, and the lab classes explain the how.

    In the same vain the documentation should explain why graphics drivers are structured the way they are, and the example driver should be commented to explain how it was structured the way it was.

    Comment


    • #32
      Ahh, now I understand. Like you, I'm a big believer in keeping architectural documentation separate from the "as built" documentation which explains the specifics of the code.

      The issue here is that the "standalone documentation" in this case would *not* be describing the software architecture and design rationale; instead it would be explaining how to program the chip. That's the only reason I'm thinking embedding the high level docco might be better than a separate doc.

      For normal development I agree completely that high level docs & code should be separate.

      Comment


      • #33
        Originally posted by bridgman View Post
        Ahh, now I understand. Like you, I'm a big believer in keeping architectural documentation separate from the "as built" documentation which explains the specifics of the code.

        The issue here is that the "standalone documentation" in this case would *not* be describing the software architecture and design rationale; instead it would be explaining how to program the chip. That's the only reason I'm thinking embedding the high level docco might be better than a separate doc.

        For normal development I agree completely that high level docs & code should be separate.
        Ok I got ya. I can understand why you'll do it that way

        Comment


        • #34
          isn't the week over now...? Has any documentation come?

          Comment


          • #35
            Today is the start of the week for when it will be released.
            Michael Larabel
            http://www.michaellarabel.com/

            Comment


            • #36
              oh..
              ah well.. at least we get it, that's what's important...

              Comment


              • #37
                I'm very much looking forward to digging through the tcore code and additional
                documentation. Keep up the good work AMD and bridgman, we all appreciate it. :-)

                Comment


                • #38
                  Originally posted by bridgman View Post
                  Ahh, now I understand. Like you, I'm a big believer in keeping architectural documentation separate from the "as built" documentation which explains the specifics of the code.

                  The issue here is that the "standalone documentation" in this case would *not* be describing the software architecture and design rationale; instead it would be explaining how to program the chip. That's the only reason I'm thinking embedding the high level docco might be better than a separate doc.

                  For normal development I agree completely that high level docs & code should be separate.
                  The problem with embedding the documentation in the code is that unless you state what is a by product of the hardware and what is a by product of the software it's much harder to rewrite parts of the driver since we won't know what's a limitation of the hardware and what's a limitation of the programmer/driver design.

                  Clearly documenting when something is a limitation of the hardware and of the software is actually pretty hard and could easily be just as hard as documenting the hardware separately with small snippets of code that just do what is necessary for that section, leaving the driver developer to combine/rewrite those snippets together to form a driver.

                  Ultimately what a developer wants is a graph of dependencies and requirements , and conceptually their driver will be one of the possible sub-graphs with a specific layout.

                  Comment


                  • #39
                    Yeah, I was thinking the same thing. The problem is that the code will be dual-use, ie it will serve as sample (instructional) code but chunks of it will probably be pasted into other drivers.

                    I'm not worried about discriminating between HW and SW restrictions (we're talking about comments like "register XYZ needs to be set before ABC or the chip hangs") but loading the code up with HW-related comments is great for instructional code but not so good if the code is also being used in a production driver.

                    I guess this is why "not documenting" seems like the universal solution to so many people

                    Comment


                    • #40
                      Originally posted by bridgman View Post
                      Yeah, I was thinking the same thing. The problem is that the code will be dual-use, ie it will serve as sample (instructional) code but chunks of it will probably be pasted into other drivers.

                      I'm not worried about discriminating between HW and SW restrictions (we're talking about comments like "register XYZ needs to be set before ABC or the chip hangs") but loading the code up with HW-related comments is great for instructional code but not so good if the code is also being used in a production driver.

                      I guess this is why "not documenting" seems like the universal solution to so many people
                      Well, All I can say s thank you for all your efforts. I know that in many cases it may seem like a thankless trivial job. But in this case, "You be da man, man!!"

                      Keep up the great work and any way that it gets implemented is better then nothing at all.

                      Comment


                      • #41
                        Originally posted by bridgman View Post
                        I guess this is why "not documenting" seems like the universal solution to so many people
                        Yanno...

                        I've always held the position that you don't need to be band-aiding silicon bugs with driver "fixes". It might be a universal solution, but if you've got a lot of those things you might want to re-think your engineering process and quality process- because you don't have the quality there. I'd consider documenting things something of an accountability thing. If you can hide embarrassing crap with driver cover-ups, then you tend to not care as much on the silicon side with quality- when both software AND hardware honestly need to be much more dead-on than it seems to have been getting lately.

                        Design flaws are design flaws. You should be striving to AVOID them, not hide them.

                        But, I suspect I'm a preaching to the choir a bit here, aren't I? >:-)

                        Comment


                        • #42
                          >>But, I suspect I'm a preaching to the choir a bit here, aren't I? >:-)

                          Just a bit

                          Comment


                          • #43
                            Originally posted by bridgman View Post
                            >>But, I suspect I'm a preaching to the choir a bit here, aren't I? >:-)

                            Just a bit
                            Believe me when I say I'm VERY glad that this is the case.

                            I just wish we'd started this journey with AMD about 6 or so months earlier- we'd be looking at a better picture, I suspect, if we had. Oh, well, it's getting much better each time we see the docs, so I'm not going to gripe TOO much... >:-)

                            Comment


                            • #44
                              One thing which I don't understand is that why do we ship code from radeon to radeonhd and from radeonhd to radeon?

                              Why don't we just migrate these two drivers together ^^ It would be nice easier to select appropriate driver for own use then when you just need to remember to put "ati" as driver =)

                              I hope that these docs which are going to be released will help my system:
                              00:00.0 Host bridge: ATI Technologies Inc RS480 Host Bridge (rev 10)
                              01:05.0 VGA compatible controller: ATI Technologies Inc RS485 [Radeon Xpress 1100 IGP]

                              I miss only two things: dri + power saving

                              Comment


                              • #45
                                Originally posted by Xemanth View Post
                                One thing which I don't understand is that why do we ship code from radeon to radeonhd and from radeonhd to radeon?

                                Why don't we just migrate these two drivers together ^^ It would be nice easier to select appropriate driver for own use then when you just need to remember to put "ati" as driver =)

                                I hope that these docs which are going to be released will help my system:
                                00:00.0 Host bridge: ATI Technologies Inc RS480 Host Bridge (rev 10)
                                01:05.0 VGA compatible controller: ATI Technologies Inc RS485 [Radeon Xpress 1100 IGP]

                                I miss only two things: dri + power saving
                                well, the radeonhd is pure code from the documentation and includes some code from the radeon one for things that work in about the same way. the problem is that radeon driver includes a lot of reverse engineered code which in the future won't be needed. then there's another problem with older chips which cannot be supported immediately with a new code driver as radeonhd. it was said here that in the future the oss ati drivers would merge all into one single driver, but for that we'll have to wait one or 2 years if not more.

                                the next documentation drop won't help your's and mine board... that board (xpress 200m) is quite known and it's reported to both work and not work. it seems that it has a proper soul and intelligence and acts accordingly to what it wants. we could say that ati has created the first artificial intelligence in the world with this board.

                                Comment

                                Working...
                                X