AMD Documentation Drop Next Week

[duby229]

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.

[bridgman]

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.

[duby229]

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

[wiscados]

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

[Michael]

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

[wiscados]

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

[olivermcfadden]

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

[Ze..]

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.

[bridgman]

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

[duby229]

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.