radeonreg.py is a python script that uses R3xx_3D_Registers.txt and
R5xx_Acceleration_v1.?.txt, created using:
pdftotext -layout -nopgbrk -f 5 R3xx_3D_Registers.pdf
pdftotext -layout -nopgbrk -f 145 R5xx_Acceleration_v1.4.pdf
It parses these files as best it can and generates a resulting XML document
that should, but does not comply with the rules-ng specification.

**********************************************************
* DO NOT REPLACE THE UPDATED XML FILE, IT'S HAND EDITED! *
**********************************************************

1) Abstract
In writing a gallium pipe driver for r300/r500 cards I found that the header
containing register information has a lot of oddities and suffers from being
hand-crafted over many years. Pekka Paalanen told me about an old noveau
project called rules-ng, designed to hold a register specification. Looking at
it it seemed viable to convert the AMD documentation to this format, so that it
could be converted to any kind of header we would like.

2) Execution
AMD don't format their documents in a particularly nice way for us to process
so I had to create some seriously evil regular expressions in order to extract
the information somewhat correctly.

3) Aftermath
So we get the information out but with no way to properly know what information
is correct and what needs looking at. I can say with some degree of certainty
that the only enumerations are incorrect. Bitfield descriptions CAN contain
superfluous information that are leaked over from the enumeration held inside
it. This happens because AMD put enumerations in many different forms and
styles making it impossible to detect them all properly.
I have ensured that ALL registers in the documentation have been extracted.

4) Solution
Human intervention. Sadly this seems to be the only way to properly eliminate
errors. This also means that:

*************************************************************************
* radeonreg.py SHOULD NOT BE CHANGED IN ORDER TO REGENERATE r300reg.xml *
*************************************************************************

5) Uses
There are various uses for a rules-ng file. The inspiration came from header
generation but it can also be used to generate HTML documentation with built-in
search, or make a lookup table for register addresses
( see http://cgit.freedesktop.org/~jsindholt/rsim ).