Intel Releases 5,000 Pages of Open-Source Haswell Documentation 111
An anonymous reader writes "Intel has ended out 2013 by publishing 5,000 pages of new GPU documentation about their latest generation 'Haswell' graphics hardware. The new documentation complements their longstanding open-source Linux graphics driver that has supported Haswell HD / Iris Graphics since last year. The new documentation covers the hardware registers and special information for 3D, video acceleration, performance counters, and GPGPU programming."
Dear Nvidia... (Score:5, Insightful)
Code. (Score:4, Insightful)
Documentation is ONE PART. It says what the design was supposed to be like.
Then you have errata and variations - when some of the hardware doesn't correspond to the documentation and acts differently.
Then you have examples - where someone shows you how to, e.g. draw a simple triangle using the documented opcodes and all of the boilerplate and set up necessary.
And then you have actual working code. Where you give away, for example, a complete implementation that conforms to a higher, standardised API and issues instructions to the hardware to perform those actions.
Out of all of those, documentation is the easiest thing to do. You can just (for example, just flicked through a PDF from that site) say that instruction X transposes a matrix. No idea of performance, whether that's the recommended way, what it contends with, how it works, whether the Intel drivers use that themselves, whether it's a legacy function, whether it has huge constraints on its use.
Without some code, it's all just fancy tech sheets. Sure, better than nothing, but a long way from actual co-operation. I'm not saying Intel don't co-operate in other areas, but documentation like this? That's the "quick reference" stuff for when your thousands of lines of existing example code don't act like you expect when you tweak them and you look up what that operand is supposed to do and how.
Put a hardware driver author in front of a documentation pack and a compiler, and tell him to write a driver, and he'll tell you to fuck off.
Put a hardware driver author in front of many working examples of device, with debug-level access, with example source (that he can't just copy due to licensing), errata, a direct line to cooperative hardware engineers AND this documentation and he'll start.
This is why I've never been that bothered by documentation releases, or even unmaintained source-drops. Supposedly Broadcom did something similar for the RPi's graphics chips. I think we're still waiting on anything that's not a binary driver there. And we have this sort of stuff for some ancient 3D graphics cards - it's just not as easy as reading it all and then sitting down to write a driver.
Intel, nVidia, ATI: Give us drivers with code that have no reliance on "black box" information/code, and we'll be happy. Until then, it's just lip-service. And you know that. That's why you don't release this kind of stuff for graphics chips, and nor does anyone else. Because you can drop this in someone's lap and years later STILL end up being pestered to the ends of the earth for an open-source driver (or assistance to help write one) because it doesn't exist.
Code is a lot more than writing things to perform a protocol described in the documentation. If only it were that easy.
Re:is it complete? (Score:2, Insightful)
Re:Code. (Score:5, Insightful)
You make a good point, however you are incorrect. As an author of a handful of drivers, and contributor to a handful more - we like specs. If you are incapable of taking an RFC or spec and outputting a working driver, then you aren't quite the programmer you think you are. Specs are often all a driver author ever receives, and you should be able to produce working code with nothing else. It's *nice* if the vendor sends best practices or additional notes about deprecation of certain methods...but it's not the norm, and should not be expected. Being a good developer means being able to benchmark methods described in specs and determine what performs best, and when that applies.
Re:Code. (Score:4, Insightful)
About 15 years ago, my company (a producer of VMEbus and CompactPCI boards) designed a video module. We used a Trident mobile graphics chip. Unfortunately, we were attempting to use it with a PowerPC, not an x86 CPU. We had the big user manual for the chip, but when we programmed all the registers according to the published configuration info, it refused to initialize.
We then were given the BIOS object code from the factory (they wouldn't share the x86 assembly source code). We disassembled the code. It was such a tangled web of spaghetti that we never did figure out how to get the part initialized, and the factory app engineering team was unable to tell us how to do so either.
We eventually dumped the part and used an Intel part with C source code available. It worked just fine.
Re:Dear Nvidia... (Score:4, Insightful)
The other thing is, well, the documentation simply doesn't exist. Having worked with quite a few ASIC vendors, inside and out, I can tell you the modern SoC if heavily undocumented. For a good chunk of the blocks, unless they're external IP (from say, Synopsys, Cadence or ARM), there IS no documentation other than a register list.
Yes, the documentation may just be a register list. Nothing to tell you how you should drive the hardware, if the registers have to be programmed in a certain way, or if there's tricks and other things that are important to know. Or even how some data structures need to be laid out in memory for hardware (you may get a brief layout, but that's it). Any my favorite - how the hardware reacts to an error. Sometimes it just plain locks up requiring a full reset. Other times it sets some strange error bit that must be cleared in order to resume functionality. If you're lucky to know how to clear the error.
Oh, and how does a software developer find out such information? Easy, they ask the ASIC designer how they envisioned the thing to work. Sometimes they're helpful and tell you exactly what you need to know, but they can be terse and expect you to figure out their thinking. And sometimes what you want to do LOOKS possible from the registers, only to find out that no, you just cannot program the bits that way and no, you shouldn't try.
That's probably why Intel took so long to get the documentation out - Haswell has been out since what, April? And only now they release the documentation? Well, it's probably because Intel was getting the whole whack together from random designer notes, software design, etc. Then bringing all that together (Intel creates some of the best documentation around) and editing it and all that.
For the most part, nVidia and AMD probably DON'T have much in the way of documentation on the latest GPUs. Intel does, and only because they spend time and effort doing it - but Intel's also huge and has a lot of cash to have a bunch of engineers sitting around writing documentation exclusively.
If you think OSS people hate writing documentation - it's no better when it's commercial development - again, the project usually doesn't allow for much documentation to be created. And things like GPUs which change frequently, well, by the time the documents are written, it's obseleted 3 times over.