src/freedreno/registers/rules-ng-ng.txt

   1 1. Introduction
   2
   3 rules-ng is a package consisting of a database of nvidia GPU registers in XML
   4 format, and tools made to parse this database and do useful work with it. It
   5 is in mostly usable state, but there are some annoyances that prevent its
   6 adoption as the home of all nouveau documentation.
   7
   8 Note that this document and rules-ng understands "register" quite liberally as
   9 "anything that has an address and can have a value in it, written to it, or
  10 read to it". This includes conventional MMIO registers, as well as fields of
  11 memory structures and grobj methods.
  12
  13 Its parsable XML format is supposed to solve three problems:
  14
  15  - serve as actual documentation for the known registers: supports attaching
  16    arbitrary text in <doc> tags and generating HTML for easy reading.
  17  - name -> hex translation: supports generating C headers that #define all
  18    known registers, bitfields and enum values as C constants.
  19  - hex -> name translation: you tell it the address or address+value of a
  20    register, and it decodes the address to its symbolic name, and the value to
  21    its constituting bitfields, if any. Useful for decoding mmio-traces /
  22    renouveau dumps, as well as standalone use.
  23
  24 What's non-trivial about all this [ie. why rules-ng is not a long series of
  25 plain address - name - documentation tuples]:
  26
  27  - The registers may be split into bitfields, each with a different purpose
  28    and name [and separate documentation].
  29  - The registers/bitfields may accept values from a predefined set [enum],
  30    each with a different meaning. Each value also has a name and
  31    documentation.
  32  - The registers may come in multiple copies, forming arrays. They can also
  33    form logical groups. And these groups can also come in multiple copies,
  34    forming larger arrays... and you get a hierarchical structure.
  35  - There are multiple different GPU chipsets. The available register set
  36    changed between these chipsets - sometimes only a few registers, sometimes
  37    half the card was remade from scratch. More annoyingly, sometimes some
  38    registers move from one place to another, but are otherwise unchanged.
  39    Also [nvidia-specific], new grobj classes are sometimes really just new
  40    revisions of a base class with a few methods changed. In both of these
  41    cases, we want to avoid duplication as much as possible.
  42
  43 2. Proposed new XML format
  44
  45 2.1. General tags
  46
  47 Root tag is <database>. There is one per the whole file and it should contain
  48 everything else.
  49
  50 <brief> and <doc> are tags that can appear inside any other tag, and document
  51 whatever it defines. <brief> is supposed to be a short one-line description
  52 giving a rough idea what a given item is for if no sufficiently descriptive
  53 name was used. <doc> can be of any length, can contain some html and html-like
  54 tags, and is supposed to describe a given item in as much detail as needed.
  55 There should be at most one <doc> and at most one <brief> tag for any parent.
  56
  57 Tags that define top-level entities include:
  58
  59  <domain>: Declares an addressing space containing registers
  60  <group>: Declares a block of registers, expected to be included by one or
  61           more <domain>s
  62  <bitset>: Declares a list of applicable bitfields for some register
  63  <enum>: Declares a list of related symbolic values. Can describe params to
  64          a register/bitfield, or discriminate between card variants.
  65
  66 Each of these has an associated global name used to refer to them from other
  67 parts of database. As a convenience, and to allow related stuff to be kept
  68 together, the top-level entities are allowed to occur pretty much anywhere
  69 inside the XML file except inside <doc> tags. This implies no scoping,
  70 however: the effect is the same as putting the entity right below <database>.
  71 If two top-level elements of the same type and name are defined, they'll be
  72 merged into a single one, as if contents of one were written right after
  73 contents of the other. All attributes of the merged tags need to match.
  74
  75 Another top-level tag that can be used anywhere is the <import> tag. It's used
  76 like <import file="foo.xml"/> and makes all of foo.xml's definitions available
  77 to the containing file. If a single file is <import>ed more than one time, all
  78 <import>s other than the first are ignored.
  79
  80 2.2. Domains
  81
  82 All register definitions ultimately belong to a <domain>. <domain> is
  83 basically just a single address space. So we'll have a domain for the MMIO
  84 BAR, one for each type of memory structure we need to describe, a domain for
  85 the grobj/FIFO methods, and a domain for each indirect index-data pair used to
  86 access something useful. <domain> can have the following attributes:
  87
  88  - name [required]: The name of the domain.
  89  - width [optional]: the size, in bits, of a single addressable unit. This is
  90    8 by default for usual byte-addressable memory, but 32 can be useful
  91    occasionally for indexed spaces of 32-bit cells. Values sane enough to
  92    support for now include 8, 16, 32, 64.
  93  - size [optional]: total number of addressable units it spans. Can be
  94    undefined if you don't know it or it doesn't make sense. As a special
  95    exception to the merging rules, size attribute need not be specified on all
  96    tags that will result in a merged domain: tags with size can be merged with
  97    tags without size, resulting in merged domain that has size. Error only
  98    happens when the merged domains both have sizes, and the sizes differ.
  99  - bare [optional]: if set to "no", all children items will have the domain
 100    name prepended to their names. If set to "yes", such prefixing doesn't
 101    happen. Default is "no".
 102  - prefix [optional]: selects the string that should be prepended to name
 103    of every child item. The special value "none" means no prefix, and is the
 104    default. All other values are looked up as <enum> names and, for each child
 105    item, its name is prefixed with name of the earliest variant in the given
 106    enum that supports given item.
 107
 108 <domain name="NV_MMIO" size="0x1000000" prefix="chipset" bare="yes">
 109         <reg32 offset="0" name="PMC_BOOT_0" />
 110         <reg32 offset="4" name="PMC_BOOT_1" varset="chipset" variants="NV10-" />
 111         <reg32 offset="0x100" name="PMC_INTR" />
 112 </domain>
 113
 114 Describes a space with 0x1000000 of 8-bit addressable cells. Cells 0-3 belong
 115 to NV04_PMC_BOOT_0 register, 4-7 belong to NV10_PMC_BOOT_1 register,
 116 0x100-0x103 belong to NV04_PMC_INTR register, and remaining cells are either
 117 unused or unknown. The generated .h definitions are:
 118
 119 #define NV_MMIO__SIZE           0x1000000
 120 #define NV04_PMC_BOOT_0         0
 121 #define NV10_PMC_BOOT_1         4
 122 #define NV04_PMC_INTR           0x100
 123
 124 <domain name="NV50_PFB_VM_TRAP" width="32" size="6">
 125         <reg32 offset="0" name="STATUS" />
 126         <reg32 offset="1" name="CHANNEL" />
 127         <reg32 offset="2" name="UNK2" />
 128         <reg32 offset="3" name="ADDRLOW" />
 129         <reg32 offset="4" name="ADDRMID" />
 130         <reg32 offset="5" name="ADDRHIGH" />
 131 </domain>
 132
 133 Defines a 6-cell address space with each cell 32 bits in size and
 134 corresponding to a single register. Definitions are:
 135
 136 #define NV50_PFB_VM_TRAP__SIZE          6
 137 #define NV50_PFB_VM_TRAP_STATUS         0
 138 #define NV50_PFB_VM_TRAP_CHANNEL        1
 139 #define NV50_PFB_VM_TRAP_UNK2           2
 140 #define NV50_PFB_VM_TRAP_ADDRLOW        3
 141 #define NV50_PFB_VM_TRAP_ADDRMID        4
 142 #define NV50_PFB_VM_TRAP_ADDRHIGH       5
 143
 144 2.3. Registers
 145
 146 What we really want all the time is defining registers. This is done with
 147 <reg8>, <reg16>, <reg32> or <reg64> tags. The register of course takes
 148 reg_width / domain_width cells in the domain. It's an error to define a
 149 register with smaller width than the domain it's in. The <reg*> attributes
 150 are:
 151
 152  - name [required]: the name of the register
 153  - offset [required]: the offset of the register
 154  - access [optional]: "rw" [default], "r", or "w" to mark the register as
 155    read-write, read-only, or write-only. Only makes sense for real MMIO
 156    domains.
 157  - varset [optional]: the <enum> to choose from by the variant attribute.
 158    Defaults to first <enum> used in currently active prefix.
 159  - variants [optional]: space-separated list of and variant ranges that this
 160    register is present on. The items of this list can be:
 161     - var1: a single variant
 162     - var1-var2: all variants starting with var1 up to and including var2
 163     - var1:var2: all variants starting with var1 up to, but not including var2
 164     - :var1: all variants before var1
 165     - -var1: all variants up to and including var1
 166     - var1-: all variants starting from var1
 167  - type [optional]: How to interpret the contents of this register.
 168     - "uint": unsigned decimal integer
 169     - "int": signed decimal integer
 170     - "hex": unsigned hexadecimal integer
 171     - "float" IEEE 16-bit, 32-bit or 64-bit floating point format, depending
 172       on register/bitfield size
 173     - "boolean": a boolean value: 0 is false, 1 is true
 174     - any defined enum name: value from that anum
 175     - "enum": value from the inline <value> tags in this <reg*>
 176     - any defined bitset name: value decoded further according to that bitset
 177     - "bitset": value decoded further according to the inline <bitfield>
 178       tags
 179     - any defined domain name: value decoded as an offset in that domain
 180    The default is "bitset" if there are inline <bitfield> tags present,
 181    otherwise "enum" if there are inline <value> tags present, otherwise
 182    "boolean" if this is a bitfield with width 1, otherwise "hex".
 183  - shr [optional]: the value in this register is the real value shifted right
 184    by this many bits. Ie. for register with shr="12", register value 0x1234
 185    should be interpreted as 0x1234000. May sound too specific, but happens
 186    quite often in nvidia hardware.
 187  - length [optional]: if specified to be other than 1, the register is treated
 188    as if it was enclosed in an anonymous <stripe> with corresponding length
 189    and stride attributes, except the __ESIZE and __LEN stripe defines are
 190    emitted with the register's name. If not specified, defaults to 1.
 191  - stride [optional]: the stride value to use if length is non-1. Defaults to
 192    the register's size in cells.
 193
 194 The definitions emitted for a non-stripe register include only its offset and
 195 shr value. Other informations are generally expected to be a part of code
 196 logic anyway:
 197
 198 <reg32 offset="0x400784" name="PGRAPH_CTXCTL_SWAP" shr="12" />
 199
 200 results in
 201
 202 #define PGRAPH_CTXCTL_SWAP      0x400784
 203 #define PGRAPH_CTXCTL_SWAP__SHR 12
 204
 205 For striped registers, __LEN and __ESIZE definitions like <stripe> are emitted
 206 too:
 207
 208 <!-- in a 8-bit domain -->
 209 <reg32 offset="0x0600" name="NV50_COMPUTE_USER_PARAM" length="64" />
 210
 211 results in
 212
 213 #define NV50_COMPUTE_USER_PARAM(i)      (0x600 + (i)*4)
 214 #define NV50_COMPUTE_USER_PARAM__LEN    64
 215 #define NV50_COMPUTE_USER_PARAM__ESIZE  4
 216
 217 The <reg*> tags can also contain either bitfield definitions, or enum value
 218 definitions.
 219
 220 2.4. Enums and variants
 221
 222 Enum is, basically, a set of values. They're defined by <enum> tag with the
 223 following attributes:
 224
 225  - name [required]: an identifying name.
 226  - inline [optional]: "yes" or "no", with "no" being the default. Selects if
 227    this enum should emit its own definitions in .h file, or be inlined into
 228    any <reg*> / <bitfield> definitions that reference it.
 229  - bare [optional]: only for no-inline enums, behaves like bare attribute
 230    to <domain>
 231  - prefix [optional]: only for no-inline enums, behaves like prefix attribute
 232    to <domain>.
 233
 234 The <enum> tag contains <value> tags with the following attributes:
 235
 236  - name [required]: the name of the value
 237  - value [optional]: the value
 238  - varset [optional]: like in <reg*>
 239  - variants [optional]: like in <reg*>
 240
 241 The <enum>s are referenced from inside <reg*> and <bitfield> tags by setting
 242 the type attribute to the name of the enum. For single-use enums, the <value>
 243 tags can also be written directly inside <reg*> tag.
 244
 245 <enum name="SURFACE_FORMAT" prefix="chipset">
 246         <value value="6" name="A8R8G8B8" />
 247         <value value="0x12" name="A8R8G8B8_RECT" variants="NV10-" />
 248 </enum>
 249
 250 <enum name="gl_shade_model" inline="yes">
 251         <value value="0x1d00" name="FLAT" />
 252         <value value="0x1d01" name="SMOOTH" />
 253 </enum>
 254
 255 <reg32 offset="0x1234" name="TEXTURE_FORMAT" type="SURFACE_FORMAT" />
 256 <reg32 offset="0x1238" name="SHADE_MODEL" type="gl_shade_model" />
 257 <reg32 offset="0x123c" name="PATTERN_SELECT">
 258         <value value="1" name="MONO" />
 259         <value value="2" name="COLOR" />
 260 </reg32>
 261
 262 Result:
 263
 264 #define NV04_SURFACE_FORMAT_A8R8G8B8            6
 265 #define NV04_SURFACE_FORMAT_A8R8G8B8_RECT       0x12
 266 #define TEXTURE_FORMAT                          0x1234
 267 #define SHADE_MODEL                             0x1238
 268 #define     SHADE_MODEL_FLAT                    0x1d00
 269 #define     SHADE_MODEL_SMOOTH                  0x1d01
 270 #define PATTERN_SELECT                          0x123c
 271 #define     PATTERN_SELECT_MONO                 1
 272 #define     PATTERN_SELECT_COLOR                2
 273
 274 Another use for enums is describing variants: slightly different versions of
 275 cards, objects, etc. The varset and variant attributes of most tags allow
 276 defining items that are only present when you're dealing with something of the
 277 matching variant. The variant space is "multidimensional" - so you can have
 278 a variant "dimension" representing what GPU chipset you're using at the
 279 moment, and another dimension representing what grobj class you're dealing
 280 with [taken from another enum]. Both of these can be independent.
 281
 282 <enum name="chipset">
 283         <brief>The chipset of the card</brief>
 284         <value name="NV04">
 285                 <brief>RIVA TNT</brief>
 286         </value>
 287         <value name="NV05">
 288                 <brief>RIVA TNT2</brief>
 289         </value>
 290         <value name="NV10">
 291                 <brief>GeForce 256</brief>
 292         </value>
 293         <value name="NV50">
 294                 <brief>G80: GeForce 8800 GTX, Tesla *870, ...</brief>
 295         </value>
 296         <value name="NV84">
 297                 <brief>G84: GeForce 8600 GT, ...</brief>
 298         </value>
 299         <value name="NVA0">
 300                 <brief>G200: GeForce 260 GTX, Tesla C1060, ...</brief>
 301         </value>
 302         <value name="NVA5">
 303                 <brief>GT216: GeForce GT 220</brief>
 304         </value>
 305 </enum>
 306
 307 If enabled for a given domain, the name of the earliest variant to support
 308 a given register / bitfield / value / whatever will be automatically prepended
 309 to its name. For this purpose, "earliest" is defined as "comes first in the
 310 XML file".
 311
 312 <enum>s used for this purpose can still be used as normal enums. And can even
 313 have variant-specific values referencing another <enum>. Example:
 314
 315 <enum name="grobj-class" bare="yes" prefix="chipset">
 316         <value name="MEMORY_TO_MEMORY_FORMAT" value="0x0039" variants=":NV50" />
 317         <value name="MEMORY_TO_MEMORY_FORMAT" value="0x5039" variants="NV50-" />
 318         <value name="2D" value="0x502d" variants="NV50-" />
 319         <value name="TCL" value="0x5097" variants="NV50:NVA0" />
 320         <value name="TCL" value="0x8297" variants="NV84" />
 321         <value name="COMPUTE" value="0x50c0" variants="NV50-" />
 322 </enum>
 323
 324 In generated .h file, this will result in:
 325
 326 #define NV04_MEMORY_TO_MEMORY_FORMAT    0x0039
 327 #define NV50_MEMORY_TO_MEMORY_FORMAT    0x5039
 328 #define NV50_2D                         0x502d
 329 #define NV50_TCL                        0x5097
 330 #define NV84_TCL                        0x8297
 331 #define NV50_COMPUTE                    0x50c0
 332
 333 2.5. Bitfields
 334
 335 Often, registers store not a single full-width value, but are split into
 336 bitfields. Like values can be grouped in enums, bitfields can be called in
 337 bitsets. The <bitset> tag has the same set of attributes as <enum> tag, and
 338 contains <bitfield> tags with the following attributes:
 339
 340  - name [required]: name of the bitfield
 341  - low [required]: index of the lowest bit belonging to this bitfield. bits
 342    are counted from 0, LSB-first.
 343  - high [required]: index of the highest bit belonging to this bitfield.
 344  - varset [optional]: like in <reg*>
 345  - variants [optional]: like in <reg*>
 346  - type [optional]: like in <reg*>
 347  - shr [optional]: like in <reg*>
 348
 349 Like <value>s, <bitfield>s are also allowed to be written directly inside
 350 <reg*> tags.
 351
 352 <bitfield>s themselves can contain <value>s. The defines generated for
 353 <bitfield>s include "name__MASK" equal to the bitmask corresponding to given
 354 bitfield, "name__SHIFT" equal to the low attribute, "name__SHR" equal to
 355 the shr attribute [if defined]. Single-bit bitfields with type "boolean" are
 356 treated specially, and get "name" defined to the bitmask instead. If the
 357 bitfield contains any <value>s, <bitfield>s, or references an inlined
 358 enum/bitset, defines for them are also generated, pre-shifted to the correct
 359 position. Example:
 360
 361 <enum name="nv03_operation" inline="yes">
 362         <value value="0" name="SRCCOPY_AND" />
 363         <value value="1" name="ROP_AND" />
 364         <value value="2" name="BLEND_AND" />
 365         <value value="3" name="SRCCOPY" />
 366         <value value="4" name="SRCCOPY_PRE" />
 367         <value value="5" name="BLEND_PRE" />
 368 </enum>
 369
 370 <bitset name="NV04_GROBJ_1">
 371         <bitfield high="7" low="0" name="GRCLASS" />
 372         <bitfield high="12" low="12" name="CHROMA_KEY" />
 373         <bitfield high="13" low="13" name="USER_CLIP" />
 374         <bitfield high="14" low="14" name="SWIZZLE" />
 375         <bitfield high="17" low="15" name="PATCH_CONFIG" type="nv03_operation" />
 376         <!-- ... -->
 377 </bitset>
 378
 379 <bitset name="xy16" inline="yes">
 380         <bitfield high="15" low="0" name="X" />
 381         <bitfield high="31" low="16" name="Y" />
 382 </bitset>
 383
 384 <bitset name="nv50_vic" inline="yes">
 385         <bitfield high="0" low="0" name="X"/>
 386         <bitfield high="1" low="1" name="Y"/>
 387         <bitfield high="2" low="2" name="Z"/>
 388         <bitfield high="3" low="3" name="W"/>
 389 </bitset>
 390
 391 <reg32 offset="0x40014c" name="PGRAPH_CTX_SWITCH_1" type="NV04_GROBJ_1" />
 392
 393 <reg32 offset="0x0404" name="FORMAT">
 394         <bitfield high="15" low="0" name="PITCH" />
 395         <bitfield high="23" low="16" name="ORIGIN" />
 396         <bitfield high="31" low="24" name="FILTER" />
 397 </reg32>
 398
 399 <reg32 offset="0x040c" name="POINT" type="xy16" />
 400
 401 <reg32 offset="0x1988" name="FP_INTERPOLANT_CTRL">
 402         <bitfield name="UMASK" high="31" low="24" type="nv50_vic"/>
 403         <bitfield name="COUNT_NONFLAT" high="23" low="16" type="int"/>
 404         <bitfield name="OFFSET" high="15" low="8" type="int"/>
 405         <bitfield name="COUNT" high="7" low="0" type="int"/>
 406 </reg32>
 407
 408 Result:
 409
 410 #define NV04_GROBJ_1_GRCLASS__MASK              0x000000ff
 411 #define NV04_GROBJ_1_GRCLASS__SHIFT             0
 412 #define NV04_GROBJ_1_CHROMA_KEY                 0x00001000
 413 #define NV04_GROBJ_1_USER_CLIP                  0x00002000
 414 #define NV04_GROBJ_1_SWIZZLE                    0x00004000
 415 #define NV04_GROBJ_1_PATCH_CONFIG__MASK         0x00038000
 416 #define NV04_GROBJ_1_PATCH_CONFIG__SHIFT        15
 417 #define NV04_GROBJ_1_PATCH_CONFIG_SRCCOPY_AND   0x00000000
 418 #define NV04_GROBJ_1_PATCH_CONFIG_ROP_AND       0x00008000
 419 #define NV04_GROBJ_1_PATCH_CONFIG_BLEND_AND     0x00010000
 420 #define NV04_GROBJ_1_PATCH_CONFIG_SRCCOPY       0x00018000
 421 #define NV04_GROBJ_1_PATCH_CONFIG_SRCCOPY_PRE   0x00020000
 422 #define NV04_GROBJ_1_PATCH_CONFIG_BLEND_PRE     0x00028000
 423
 424 #define PGRAPH_CTX_SWITCH_1                     0x40014c
 425
 426 #define FORMAT                  0x0404
 427 #define FORMAT_PITCH__MASK      0x0000ffff
 428 #define FORMAT_PITCH__SHIFT     0
 429 #define FORMAT_ORIGIN__MASM     0x00ff0000
 430 #define FORMAT_ORIGIN__SHIFT    16
 431 #define FORMAT_FILTER__MASK     0xff000000
 432 #define FORMAT_FILTER__SHIFT    24
 433
 434 #define POINT           0x040c
 435 #define POINT_X         0x0000ffff
 436 #define POINT_X__SHIFT          0
 437 #define POINT_Y         0xffff0000
 438 #define POINT_Y__SHIFT          16
 439
 440 #define FP_INTERPOLANT_CTRL                             0x00001988
 441 #define FP_INTERPOLANT_CTRL_UMASK__MASK                 0xff000000
 442 #define FP_INTERPOLANT_CTRL_UMASK__SHIFT                24
 443 #define FP_INTERPOLANT_CTRL_UMASK_X                     0x01000000
 444 #define FP_INTERPOLANT_CTRL_UMASK_Y                     0x02000000
 445 #define FP_INTERPOLANT_CTRL_UMASK_Z                     0x04000000
 446 #define FP_INTERPOLANT_CTRL_UMASK_W                     0x08000000
 447 #define FP_INTERPOLANT_CTRL_COUNT_NONFLAT__MASK         0x00ff0000
 448 #define FP_INTERPOLANT_CTRL_COUNT_NONFLAT__SHIFT        16
 449 #define FP_INTERPOLANT_CTRL_OFFSET__MASK                0x0000ff00
 450 #define FP_INTERPOLANT_CTRL_OFFSET__SHIFT               8
 451 #define FP_INTERPOLANT_CTRL_COUNT__MASK                 0x000000ff
 452 #define FP_INTERPOLANT_CTRL_COUNT__SHIFT                0
 453
 454 2.6. Arrays and stripes.
 455
 456 Sometimes you have multiple copies of a register. Sometimes you actually have
 457 multiple copies of a whole set of registers. And sometimes this set itself
 458 contains multiple copies of something. This is what <array>s are for. The
 459 <array> represents "length" units, each of size "stride" packed next to each
 460 other starting at "offset". Offsets of everything inside the array are
 461 relative to start of an element of the array. The <array> attributes include:
 462
 463  - name [required]: name of the array, also used as prefix for all items
 464    inside it
 465  - offset [required]: starting offset of the array.
 466  - stride [required]: size of a single element of the array, as well as the
 467    difference between offsets of two neighboring elements
 468  - length [required]: Number of elements in the array
 469  - varset [optional]: As in <reg*>
 470  - variants [optional]: As in <reg*>
 471
 472 The definitions emitted for an array include:
 473  - name(i) defined to be the starting offset of element i, if length > 1
 474  - name defined to be the starting offset of arrayi, if length == 1
 475  - name__LEN defined to be the length of array
 476  - name__ESIZE defined to be the stride of array
 477
 478 Also, if length is not 1, definitions for all items inside the array that
 479 involve offsets become parameter-taking C macros that calculate the offset
 480 based on array index. For nested arrays, this macro takes as many arguments
 481 as there are indices involved.
 482
 483 It's an error if an item inside an array doesn't fit inside the array element.
 484
 485 <array offset="0x408000" name="PGRAPH_TP" stride="0x1000" length="8">
 486         <array offset="0x200" name="MP" stride="0x80" length="2">
 487                 <!-- ... -->
 488                 <reg64 offset="0x70" name="TRAPPED_OPCODE" />
 489                 <!-- ... -->
 490         </array>
 491         <reg32 offset="0x314" name="MP_TRAP />
 492         <!-- ... -->
 493 </array>
 494
 495 #define PGRAPH_TP(i)                            (0x408000+(i)*0x1000)
 496 #define PGRAPH_TP__LEN                          8
 497 #define PGRAPH_TP__ESIZE                        0x1000
 498 #define PGRAPH_TP_MP(i,j)                       (0x408200+(i)*0x1000+(j)*0x80)
 499 #define PGRAPH_TP__LEN                          2
 500 #define PGRAPH_TP__ESIZE                        0x80
 501 #define PGRAPH_TP_MP_TRAPPED_OPCODE(i,j)        (0x408270+(i)*0x1000+(j)*0x80)
 502
 503 <stripe>s are somewhat similar to arrays, but don't reserve space, merely say
 504 that all items inside come in "length" copies "stride" cells apart. As opposed
 505 to <array>s, items can have offsets larger than stride, and offsets aren't
 506 automatically assumed to be a part of <stripe> unless a <reg*> explicitely
 507 hits that particular offset for some index. Also, <stripe>s of length 1 and
 508 stride 0 can be used as generic container, for example to apply a variant set
 509 or a prefix to a bigger set of elements. Attributes:
 510
 511  - name [optional]: like in <array>. If not given, no prefixing happens, and
 512    the defines for <stripe> itself aren't emitted.
 513  - offset [optional]: like <array>. Defaults to 0 if unspecified.
 514  - stride [optional]: the difference between offsets of items with indices i
 515    and i+1. Or size of the <stripe> if it makes sense in that particular
 516    context. Defaults to 0.
 517  - length [optional]: like in array. Defaults to 1.
 518  - varset [optional]: as in <reg*>
 519  - variants [optional]: as in <reg*>
 520  - prefix [optional]: as in <domain>, overrides parent's prefix option.
 521
 522 Definitions are emitted like for arrays, but:
 523  - if no name is given, the definitions for stripe itself won't be emitted
 524  - if length is 0, the length is assumed to be unknown or undefined. No __LEN
 525    is emitted in this case.
 526  - if stride is 0, __ESIZE is not emitted
 527  - it's an error to have stride 0 with length different than 1
 528
 529
 530 Examples:
 531
 532 <stripe name="PGRAPH" offset="0x400000" variants="NV04-NV05">
 533         <reg32 offset="0x100" name="INTR" />
 534         <reg32 offset="0x140" name="INTR_EN" />
 535 </stripe>
 536
 537 <stripe name="PGRAPH" offset="0x400000" variants="NV50-">
 538         <reg32 offset="0x100" name="INTR" />
 539         <reg32 offset="0x108" name="TRAP" />
 540         <reg32 offset="0x138" name="TRAP_EN" />
 541         <reg32 offset="0x13c" name="INTR_EN" />
 542 </stripe>
 543
 544 Results in:
 545
 546 #define NV04_PGRAPH             0x400000
 547 #define NV04_PGRAPH_INTR        0x400100
 548 #define NV04_PGRAPH_INTR_EN     0x400140
 549 #define NV50_PGRAPH             0x400000
 550 #define NV50_PGRAPH_INTR        0x400100
 551 #define NV50_PGRAPH_TRAP        0x400108
 552 #define NV50_PGRAPH_TRAP_EN     0x400138
 553 #define NV50_PGRAPH_INTR_EN     0x40013c
 554
 555 <stripe name="PVIDEO" offset="0x8000">
 556         <stripe offset="0x900" stride="4" length="2">
 557                 <reg32 offset="0" name="BASE" />
 558                 <reg32 offset="8" name="LIMIT" />
 559                 <reg32 offset="0x10" name="LUMINANCE" />
 560                 <reg32 offset="0x18" name="CHROMINANCE" />
 561                 <!-- ... -->
 562         </stripe>
 563 </stripe>
 564
 565 Results in:
 566
 567 #define PVIDEO_BASE             (0x8900+(i)*4)
 568 #define PVIDEO_LIMIT            (0x8908+(i)*4)
 569 #define PVIDEO_LUMINANCE        (0x8910+(i)*4)
 570 #define PVIDEO_CHROMINANCE      (0x8918+(i)*4)
 571
 572 <domain name="NV_OBJECT" bare="yes">
 573         <stripe name="OBJECT" prefix="chipset">
 574                 <reg32 offset="0x00" name="NAME" />
 575                 <reg32 offset="0x10" name="FENCE_ADDRESS_HIGH" variants="NV50-" />
 576                 <!-- more PFIFO methods -->
 577         </stripe>
 578         <stripe prefix="grobj-class">
 579                 <stripe variants="NV04_MEMORY_TO_MEMORY_FORMAT-NV05_MEMORY_TO_MEMORY_FORMAT">
 580                         <reg32 offset="0x200" name="LINEAR_IN" variants="NV50_MEMORY_TO_MEMORY_FORMAT" />
 581                         <reg32 offset="0x328" name="BUFFER_NOTIFY" />
 582                         <!-- more m2mf methods -->
 583                 </stripe>
 584                 <stripe variants="NV50_COMPUTE">
 585                         <reg32 offset="0x368" name="LAUNCH" />
 586                         <stripe name="GLOBAL" offset="0x400" stride="0x20" length="16">
 587                                 <reg32 offset="0" name="ADDRESS_HIGH" />
 588                                 <reg32 offset="4" name="ADDRESS_LOW" />
 589                                 <reg32 offset="8" name="PITCH" />
 590                                 <reg32 offset="0xc" name="LIMIT" />
 591                                 <reg32 offset="0x10" name="MODE" />
 592                         </stripe>
 593                         <!-- more NV50_COMPUTE methods -->
 594                         <reg32 offset="0x0600" name="USER_PARAM" length="64" />
 595                 </stripe>
 596         </stripe>
 597 </domain>
 598
 599 Results in:
 600
 601 #define NV01_OBJECT_NAME                                0x00
 602 #define NV50_OBJECT_FENCE_ADDRESS_HIGH                  0x10
 603 #define NV50_MEMORY_TO_MEMORY_FORMAT_LINEAR_IN          0x200
 604 #define NV04_MEMORY_TO_MEMORY_FORMAT_BUFFER_NOTIFY      0x328
 605 #define NV50_COMPUTE_LAUNCH                             0x368
 606 #define NV50_COMPUTE_GLOBAL                             0x400
 607 #define NV50_COMPUTE_GLOBAL__LEN                        16
 608 #define NV50_COMPUTE_GLOBAL__ESIZE                      0x20
 609 #define NV50_COMPUTE_GLOBAL_ADDRESS_HIGH                (0x400 + (i)*0x20)
 610 #define NV50_COMPUTE_GLOBAL_ADDRESS_LOW                 (0x404 + (i)*0x20)
 611 #define NV50_COMPUTE_GLOBAL_PITCH                       (0x408 + (i)*0x20)
 612 #define NV50_COMPUTE_GLOBAL_LIMIT                       (0x40c + (i)*0x20)
 613 #define NV50_COMPUTE_GLOBAL_MODE                        (0x410 + (i)*0x20)
 614 #define NV50_COMPUTE_USER_PARAM(i)                      (0x600 + (i)*4)
 615 #define NV50_COMPUTE_USER_PARAM__LEN                    64
 616 #define NV50_COMPUTE_USER_PARAM__ESIZE                  4
 617
 618 2.7. Groups
 619
 620 Groups are just sets of registers and/or arrays that can be copied-and-pasted
 621 together, when they're duplicated in several places in the same <domain>,
 622 two different <domain>s, or have different offsets for different variants.
 623 <group> and <use-group> only have the name attribute. <use-group> can appear
 624 wherever <reg*> can, including inside a <group>.
 625
 626 <group name="nv50_mp">
 627         <!-- ... -->
 628         <reg64 offset="0x70" name="TRAPPED_OPCODE" />
 629         <!-- ... -->
 630 </group>
 631
 632 <array offset="0x408000" name="PGRAPH_TP" stride="0x1000" length="8" variants="NV50:NVA0">
 633         <array offset="0x200" name="MP" stride="0x80" length="2">
 634                 <use-group name="nv50_mp" />
 635         </array>
 636         <!-- ... -->
 637 </array>
 638 <array offset="0x408000" name="PGRAPH_TP" stride="0x800" length="10" variants="NVA0-">
 639         <array offset="0x100" name="MP" stride="0x80" length="4">
 640                 <use-group name="nv50_mp" />
 641         </array>
 642         <!-- ... -->
 643 </array>
 644
 645 Will get you:
 646
 647 #define NV50_PGRAPH_TP_MP_TRAPPED_OPCODE(i, j)  (0x408270 + (i)*0x1000 + (j)*0x80)
 648 #define NVA0_PGRAPH_TP_MP_TRAPPED_OPCODE(i, j)  (0x408170 + (i)*0x800 + (j)*0x80)
 649
 650 3. The utilities.
 651
 652 The header generation utility will take a set of XML files and generate .h
 653 file with all of their definitions, as defined above.
 654
 655 The HTML generation utilty will take an XML file and generate HTML
 656 documentation out of it. The documentation will include the <brief> and <doc>
 657 tags in some way, as well as information from all the attributes, in some easy
 658 to read format. Some naming scheme for the HTML files should be decided, so
 659 that cross-refs to HTML documentation generated for <import>ed files will work
 660 correctly if the generator is run in both.
 661
 662 The lookup utility will perform database lookups of the following types:
 663
 664  - domain name, offset, access type, variant type[s] -> register name + array
 665    indices if applicable
 666  - the above + register value -> same as above + decoded value. For registers
 667    with bitfields, print all bitfields, and indicate if any bits not covered
 668    by the bitfields are set to 1. For registers/bitfields with enum values,
 669    print the matching one if any. For remaining registers/bitfields, print
 670    according to type attribute.
 671  - bitset name + value -> decoded value, as above
 672  - enum name + value -> decoded value, as above
 673
 674 The mmio-parse utility will parse a mmio-trace file and apply the second kind
 675 of database lookups to all memory accesses matching a given range. Some
 676 nv-specific hacks will be in order to automate the parsing: extract the
 677 chipset from PMC_BOOT_0, figure out the mmio base from PCI config, etc.
 678
 679 The renouveau-parse utility will take contents of a PFIFO pushbuffer and
 680 decode them. The splitting to method,data pair will be done by nv-specific
 681 code, then the pair will be handed over to generic rules-ng lookup.
 682
 683 4. Issues
 684
 685  - Random typing-saving feature for bitfields: make high default to same value
 686    as low, to have one less attribute for single-bit bitfields?
 687
 688  - What about allowing nameless registers and/or bitfields? These are
 689    supported by renouveau.xml and are used commonly to signify an unknown
 690    register.
 691
 692  - How about cross-ref links in <doc> tags?
 693
 694  - <translation>: do we need them? Sounds awesome and useful, but as defined
 695    by the old spec, they're quite limited. The only examples of straight
 696    translations that I know of are the legacy VGA registers and
 697    NV50_PFB_VM_TRAP. And NV01_PDAC, but I doubt anybody gives a damn about it.
 698    This list is small enough to be just handled by nv-specific hacks in
 699    mmio-trace parser if really needed.
 700
 701  - Another thing that renouveau.xml does is disassembling NV20-NV40 shaders.
 702    Do we want that in rules-ng? IMO we'd be better off hacking nv50dis to
 703    support it...