Page 4 of 6 FirstFirst ... 23456 LastLast
Results 31 to 40 of 54

Thread: AMD Documentation Drop Next Week

  1. #31
    Join Date
    Nov 2007
    Posts
    1,353

    Default

    Quote 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.

  2. #32
    Join Date
    Oct 2007
    Location
    Toronto-ish
    Posts
    7,458

    Default

    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.

  3. #33
    Join Date
    Nov 2007
    Posts
    1,353

    Default

    Quote 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

  4. #34
    Join Date
    Sep 2007
    Posts
    51

    Default

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

  5. #35

    Default

    Today is the start of the week for when it will be released.

  6. #36
    Join Date
    Sep 2007
    Posts
    51

    Default

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

  7. #37

    Default

    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. :-)

  8. #38
    Join Date
    Oct 2007
    Posts
    29

    Default

    Quote 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.

  9. #39
    Join Date
    Oct 2007
    Location
    Toronto-ish
    Posts
    7,458

    Default

    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

  10. #40
    Join Date
    Nov 2007
    Posts
    1,353

    Default

    Quote 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.

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •