src/freedreno/registers/text-format.txt

   1 1. Introduction to rules-ng-ng text format
   2
   3 This-specification defines a text format that can be converted to and from rules-ng-ng XML.
   4 It is intended to allow to create rules-ng-ng files with much less typing and with a more readable text.
   5 xml2text can convert rules-ng-ng XML to this text format
   6 text2xml can convert this text format to rules-ng-ng XML
   7
   8 This specification is an addendum to the rules-ng-ng specification and assumes familiarity with it.
   9
  10 2. Format
  11
  12 2.1. Line format
  13
  14 The initial indentation of a line is divided by 8 and the result determines the position in the document structure (similar to the Python language).
  15 A "//" anywhere in the line causes the rest to be converted to an XML comment (like C++)
  16 A line starting with ":" creates a <doc> tag with the rest of the line (excluding anything starting with //).
  17 The content of multiple lines starting with ":" is merged in a single <doc> tag.
  18
  19 2.2. Tokenization
  20
  21 The line is then tokenized.
  22 Token are generally continuous strings on non-whitespace characters, with some exceptions
  23 Some characters (such as ":", "=" and "-") form a single-character token.
  24 Text within double quotes generates a <brief> tag.
  25 Any token formatted as ATTR(VALUE) generates an ATTR="VALUE" attribute. No whitespace allowed between ATTR and the '(' character.
  26 Any token formatted as (VALUE) generates a variants="VALUE" attribute.
  27 Any token formatted as (VARSET=VALUE) generates a varset="VARSET" variants="VALUE" attribute.
  28
  29 2.3. Special token sequences
  30
  31 These sequences are recognized and extracted before matching the line format:
  32
  33 : NUM
  34         set REGLIKE to regNUM
  35         you must specify a type if the reg is anonymous
  36         the : is recognized only if it is the third or successive token (and not the last) to avoid ambiguity with bitfields and generic tags
  37
  38 { STRIDE }
  39         stride="STRIDE" attribute
  40
  41 [ LENGTH ]
  42         length="LENGTH" attribute
  43
  44 !FLAGS
  45         access="FLAGS"
  46         no whitespace allowed after '!'
  47
  48 :=
  49         at the end of the line
  50         set REGLIKE to "stripe"
  51
  52 =
  53         at the end of the line
  54         set REGLIKE to "array"
  55
  56 inline
  57         at the beginning of the line
  58         inline="yes" attribute
  59
  60 2.4. Line patterns
  61
  62 The following line patterns are understood.
  63 Only word tokens are used to match lines.
  64 All tokens with special meaning are treated separately as described above.
  65 [FOO] means that FOO is optional
  66
  67 #import "FILE"
  68         <import file="FILE"/>
  69
  70 #pragma regNUM
  71         REGLIKE is now set by default to regNUM instead of reg32
  72
  73 @TAG [NAME]
  74         <TAG name="NAME"/>
  75         use this if there are no children
  76
  77 TAG [NAME] :
  78         <TAG name="NAME">
  79         use this if there are children
  80
  81 TOKEN
  82         <value value="TOKEN" /> if inside a reg or enum and TOKEN starts with a digit
  83         <value name="TOKEN" /> if inside a reg or enum and TOKEN does not start with a digit
  84         <REGLIKE offset="TOKEN" /> otherwise
  85
  86 POS NAME
  87         <bitfield low="POS" high="POS" name="NAME"/> if inside a reg or bitset
  88         <REGLIKE offset="POS" name="NAME"> otherwise
  89
  90 LOW - HIGH NAME [TYPE]
  91         <bitfield low="LOW" high="HIGH" name="NAME" type="TYPE"/>
  92
  93 VALUE = NAME
  94         <value value="VALUE" name="NAME"/>
  95
  96 use WHAT NAME
  97         <use-WHAT name="NAME" />
  98
  99 OFFSET NAME [TYPE]
 100         <REGLIKE offset="OFFSET" name="NAME" type="TYPE">
 101