11. Introduction 2 3rules-ng is a package consisting of a database of nvidia GPU registers in XML 4format, and tools made to parse this database and do useful work with it. It 5is in mostly usable state, but there are some annoyances that prevent its 6adoption as the home of all nouveau documentation. 7 8Note 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 10read to it". This includes conventional MMIO registers, as well as fields of 11memory structures and grobj methods. 12 13Its 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 24What's non-trivial about all this [ie. why rules-ng is not a long series of 25plain 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 432. Proposed new XML format 44 452.1. General tags 46 47Root tag is <database>. There is one per the whole file and it should contain 48everything else. 49 50<brief> and <doc> are tags that can appear inside any other tag, and document 51whatever it defines. <brief> is supposed to be a short one-line description 52giving a rough idea what a given item is for if no sufficiently descriptive 53name was used. <doc> can be of any length, can contain some html and html-like 54tags, and is supposed to describe a given item in as much detail as needed. 55There should be at most one <doc> and at most one <brief> tag for any parent. 56 57Tags 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 66Each of these has an associated global name used to refer to them from other 67parts of database. As a convenience, and to allow related stuff to be kept 68together, the top-level entities are allowed to occur pretty much anywhere 69inside the XML file except inside <doc> tags. This implies no scoping, 70however: the effect is the same as putting the entity right below <database>. 71If two top-level elements of the same type and name are defined, they'll be 72merged into a single one, as if contents of one were written right after 73contents of the other. All attributes of the merged tags need to match. 74 75Another top-level tag that can be used anywhere is the <import> tag. It's used 76like <import file="foo.xml"/> and makes all of foo.xml's definitions available 77to 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 802.2. Domains 81 82All register definitions ultimately belong to a <domain>. <domain> is 83basically just a single address space. So we'll have a domain for the MMIO 84BAR, one for each type of memory structure we need to describe, a domain for 85the grobj/FIFO methods, and a domain for each indirect index-data pair used to 86access 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 114Describes a space with 0x1000000 of 8-bit addressable cells. Cells 0-3 belong 115to NV04_PMC_BOOT_0 register, 4-7 belong to NV10_PMC_BOOT_1 register, 1160x100-0x103 belong to NV04_PMC_INTR register, and remaining cells are either 117unused 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 133Defines a 6-cell address space with each cell 32 bits in size and 134corresponding 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 1442.3. Registers 145 146What 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 148reg_width / domain_width cells in the domain. It's an error to define a 149register with smaller width than the domain it's in. The <reg*> attributes 150are: 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 194The definitions emitted for a non-stripe register include only its offset and 195shr value. Other informations are generally expected to be a part of code 196logic anyway: 197 198<reg32 offset="0x400784" name="PGRAPH_CTXCTL_SWAP" shr="12" /> 199 200results in 201 202#define PGRAPH_CTXCTL_SWAP 0x400784 203#define PGRAPH_CTXCTL_SWAP__SHR 12 204 205For striped registers, __LEN and __ESIZE definitions like <stripe> are emitted 206too: 207 208<!-- in a 8-bit domain --> 209<reg32 offset="0x0600" name="NV50_COMPUTE_USER_PARAM" length="64" /> 210 211results 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 217The <reg*> tags can also contain either bitfield definitions, or enum value 218definitions. 219 2202.4. Enums and variants 221 222Enum is, basically, a set of values. They're defined by <enum> tag with the 223following 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 234The <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 241The <enum>s are referenced from inside <reg*> and <bitfield> tags by setting 242the type attribute to the name of the enum. For single-use enums, the <value> 243tags 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 262Result: 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 274Another use for enums is describing variants: slightly different versions of 275cards, objects, etc. The varset and variant attributes of most tags allow 276defining items that are only present when you're dealing with something of the 277matching variant. The variant space is "multidimensional" - so you can have 278a variant "dimension" representing what GPU chipset you're using at the 279moment, and another dimension representing what grobj class you're dealing 280with [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 307If enabled for a given domain, the name of the earliest variant to support 308a given register / bitfield / value / whatever will be automatically prepended 309to its name. For this purpose, "earliest" is defined as "comes first in the 310XML file". 311 312<enum>s used for this purpose can still be used as normal enums. And can even 313have 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 324In 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 3332.5. Bitfields 334 335Often, registers store not a single full-width value, but are split into 336bitfields. Like values can be grouped in enums, bitfields can be called in 337bitsets. The <bitset> tag has the same set of attributes as <enum> tag, and 338contains <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 349Like <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 354bitfield, "name__SHIFT" equal to the low attribute, "name__SHR" equal to 355the shr attribute [if defined]. Single-bit bitfields with type "boolean" are 356treated specially, and get "name" defined to the bitmask instead. If the 357bitfield contains any <value>s, <bitfield>s, or references an inlined 358enum/bitset, defines for them are also generated, pre-shifted to the correct 359position. 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 408Result: 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 4542.6. Arrays and stripes. 455 456Sometimes you have multiple copies of a register. Sometimes you actually have 457multiple copies of a whole set of registers. And sometimes this set itself 458contains 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 460other starting at "offset". Offsets of everything inside the array are 461relative 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 472The 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 478Also, if length is not 1, definitions for all items inside the array that 479involve offsets become parameter-taking C macros that calculate the offset 480based on array index. For nested arrays, this macro takes as many arguments 481as there are indices involved. 482 483It'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 504that all items inside come in "length" copies "stride" cells apart. As opposed 505to <array>s, items can have offsets larger than stride, and offsets aren't 506automatically assumed to be a part of <stripe> unless a <reg*> explicitely 507hits that particular offset for some index. Also, <stripe>s of length 1 and 508stride 0 can be used as generic container, for example to apply a variant set 509or 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 522Definitions 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 530Examples: 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 544Results 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 565Results 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 599Results 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 6182.7. Groups 619 620Groups are just sets of registers and/or arrays that can be copied-and-pasted 621together, when they're duplicated in several places in the same <domain>, 622two different <domain>s, or have different offsets for different variants. 623<group> and <use-group> only have the name attribute. <use-group> can appear 624wherever <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 645Will 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 6503. The utilities. 651 652The header generation utility will take a set of XML files and generate .h 653file with all of their definitions, as defined above. 654 655The HTML generation utilty will take an XML file and generate HTML 656documentation out of it. The documentation will include the <brief> and <doc> 657tags in some way, as well as information from all the attributes, in some easy 658to read format. Some naming scheme for the HTML files should be decided, so 659that cross-refs to HTML documentation generated for <import>ed files will work 660correctly if the generator is run in both. 661 662The 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 674The mmio-parse utility will parse a mmio-trace file and apply the second kind 675of database lookups to all memory accesses matching a given range. Some 676nv-specific hacks will be in order to automate the parsing: extract the 677chipset from PMC_BOOT_0, figure out the mmio base from PCI config, etc. 678 679The renouveau-parse utility will take contents of a PFIFO pushbuffer and 680decode them. The splitting to method,data pair will be done by nv-specific 681code, then the pair will be handed over to generic rules-ng lookup. 682 6834. 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... 704