1ISASPEC - XML Based ISA Specification 2===================================== 3 4isaspec provides a mechanism to describe an instruction set in xml, and 5generate a disassembler and assembler (eventually). The intention is 6to describe the instruction set more formally than hand-coded assembler 7and disassembler, and better decouple the shader compiler from the 8underlying instruction encoding to simplify dealing with instruction 9encoding differences between generations of GPU. 10 11Benefits of a formal ISA description, compared to hand-coded assemblers 12and disassemblers, include easier detection of new bit combinations that 13were not seen before in previous generations due to more rigorous 14description of bits that are expect to be '0' or '1' or 'x' (dontcare) 15and verification that different encodings don't have conflicting bits 16(ie. that the specification cannot result in more than one valid 17interpretation of any bit pattern). 18 19The isaspec tool and xml schema are intended to be generic (not specific 20to ir3), although there are currently a couple limitations due to short- 21cuts taken to get things up and running (which are mostly not inherent to 22the xml schema, and should not be too difficult to remove from the py and 23decode/disasm utility): 24 25* Maximum "field" size is 64b 26* Fixed instruction size 27 28Often times, especially when new functionality is added in later gens 29while retaining (or at least mostly retaining) backwards compatibility 30with encodings used in earlier generations, the actual encoding can be 31rather messy to describe. To support this, isaspec provides many flexible 32mechanism, such as conditional overrides and derived fields. This not 33only allows for describing an irregular instruction encoding, but also 34allows matching an existing disasm syntax (which might not have been 35design around the idea of disassembly based on a formal ISA description). 36 37Bitsets 38------- 39 40The fundamental concept of matching a bit-pattern to an instruction 41decoding/encoding is the concept of a hierarchial tree of bitsets. 42This is intended to match how the hw decodes instructions, where certain 43bits describe the instruction (and sub-encoding, and so on), and other 44bits describe various operands to the instruction. 45 46Bitsets can also be used recursively as the type of a field described 47in another bitset. 48 49The leaves of the tree of instruction bitsets represent every possible 50instruction. Deciding which instruction a bitpattern is amounts to: 51 52.. code-block:: c 53 54 m = (val & bitsets[n]->mask) & ~bitsets[n]->dontcare; 55 56 if (m == bitsets[n]->match) { 57 /* we've found the instruction description */ 58 } 59 60For example, the starting point to decode an ir3 instruction is a 64b 61bitset: 62 63.. code-block:: xml 64 65 <bitset name="#instruction" size="64"> 66 <doc> 67 Encoding of an ir3 instruction. All instructions are 64b. 68 </doc> 69 </bitset> 70 71In the first level of instruction encoding hierarchy, the high three bits 72group things into instruction "categories": 73 74.. code-block:: xml 75 76 <bitset name="#instruction-cat2" extends="#instruction"> 77 <field name="DST" low="32" high="39" type="#reg-gpr"/> 78 <field name="REPEAT" low="40" high="41" type="#rptN"/> 79 <field name="SAT" pos="42" type="bool" display="(sat)"/> 80 <field name="SS" pos="44" type="bool" display="(ss)"/> 81 <field name="UL" pos="45" type="bool" display="(ul)"/> 82 <field name="DST_CONV" pos="46" type="bool"> 83 <doc> 84 Destination register is opposite precision as source, ie. 85 if {FULL} is true then destination is half precision, and 86 visa versa. 87 </doc> 88 </field> 89 <derived name="DST_HALF" expr="#dest-half" type="bool" display="h"/> 90 <field name="EI" pos="47" type="bool" display="(ei)"/> 91 <field name="FULL" pos="52" type="bool"> 92 <doc>Full precision source registers</doc> 93 </field> 94 <field name="JP" pos="59" type="bool" display="(jp)"/> 95 <field name="SY" pos="60" type="bool" display="(sy)"/> 96 <pattern low="61" high="63">010</pattern> <!-- cat2 --> 97 <!-- 98 NOTE, both SRC1_R and SRC2_R are defined at this level because 99 SRC2_R is still a valid bit for (nopN) (REPEAT==0) for cat2 100 instructions with only a single src 101 --> 102 <field name="SRC1_R" pos="43" type="bool" display="(r)"/> 103 <field name="SRC2_R" pos="51" type="bool" display="(r)"/> 104 <derived name="ZERO" expr="#zero" type="bool" display=""/> 105 </bitset> 106 107The ``<pattern>`` elements are the part(s) that determine which leaf-node 108bitset matches against a given bit pattern. The leaf node's match/mask/ 109dontcare bitmasks are a combination of those defined at the leaf node and 110recursively each parent bitclass. 111 112For example, cat2 instructions (ALU instructions with up to two src 113registers) can have either one or two source registers: 114 115.. code-block:: xml 116 117 <bitset name="#instruction-cat2-1src" extends="#instruction-cat2"> 118 <override expr="#cat2-cat3-nop-encoding"> 119 <display> 120 {SY}{SS}{JP}{SAT}(nop{NOP}) {UL}{NAME} {EI}{DST_HALF}{DST}, {SRC1} 121 </display> 122 <derived name="NOP" expr="#cat2-cat3-nop-value" type="uint"/> 123 <field name="SRC1" low="0" high="15" type="#multisrc"> 124 <param name="ZERO" as="SRC_R"/> 125 <param name="FULL"/> 126 </field> 127 </override> 128 <display> 129 {SY}{SS}{JP}{SAT}{REPEAT}{UL}{NAME} {EI}{DST_HALF}{DST}, {SRC1} 130 </display> 131 <pattern low="16" high="31">xxxxxxxxxxxxxxxx</pattern> 132 <pattern low="48" high="50">xxx</pattern> <!-- COND --> 133 <field name="SRC1" low="0" high="15" type="#multisrc"> 134 <param name="SRC1_R" as="SRC_R"/> 135 <param name="FULL"/> 136 </field> 137 </bitset> 138 139 <bitset name="absneg.f" extends="#instruction-cat2-1src"> 140 <pattern low="53" high="58">000110</pattern> 141 </bitset> 142 143In this example, ``absneg.f`` is a concrete cat2 instruction (leaf node of 144the bitset inheritance tree) which has a single src register. At the 145``#instruction-cat2-1src`` level, bits that are used for the 2nd src arg 146and condition code (for cat2 instructions which use a condition code) are 147defined as 'x' (dontcare), which matches our understanding of the hardware 148(but also lets the disassembler flag cases where '1' bits show up in places 149we don't expect, which may signal a new instruction (sub)encoding). 150 151You'll notice that ``SRC1`` refers back to a different bitset hierarchy 152that describes various different src register encoding (used for cat2 and 153cat4 instructions), ie. GPR vs CONST vs relative GPR/CONST. For fields 154which have bitset types, parameters can be "passed" in via ``<param>`` 155elements, which can be referred to by the display template string, and/or 156expressions. For example, this helps to deal with cases where other fields 157outside of that bitset control the encoding/decoding, such as in the 158``#multisrc`` example: 159 160.. code-block:: xml 161 162 <bitset name="#multisrc" size="16"> 163 <doc> 164 Encoding for instruction source which can be GPR/CONST/IMMED 165 or relative GPR/CONST. 166 </doc> 167 </bitset> 168 169 ... 170 171 <bitset name="#multisrc-gpr" extends="#multisrc"> 172 <display> 173 {ABSNEG}{SRC_R}{HALF}{SRC} 174 </display> 175 <derived name="HALF" expr="#multisrc-half" type="bool" display="h"/> 176 <field name="SRC" low="0" high="7" type="#reg-gpr"/> 177 <pattern low="8" high="13">000000</pattern> 178 <field name="ABSNEG" low="14" high="15" type="#absneg"/> 179 </bitset> 180 181At some level in the bitset inheritance hiearchy, there is expected to be a 182``<display>`` element specifying a template string used during bitset 183decoding. The display template consists of references to fields (which may 184be derived fields) specified as ``{FIELDNAME}`` and other characters 185which are just echoed through to the resulting decoded bitset. 186 187It is possible to define a line column alignment value per field to influence 188the visual output. It needs to be pecified as ``{FIELDNAME:align=xx}``. 189 190The ``<override>`` element will be described in the next section, but it 191provides for both different decoded instruction syntax/mnemonics (when 192simply providing a different display template string) as well as instruction 193encoding where different ranges of bits have a different meaning based on 194some other bitfield (or combination of bitfields). In this example it is 195used to cover the cases where ``SRCn_R`` has a different meaning and a 196different disassembly syntax depending on whether ``REPEAT`` equals zero. 197 198Overrides 199--------- 200 201In many cases, a bitset is not convenient for describing the expected 202disasm syntax, and/or interpretation of some range of bits differs based 203on some other field or combination of fields. These *could* be modeled 204as different derived bitsets, at the expense of a combinatorical explosion 205of the size of the bitset inheritance tree. For example, *every* cat2 206(and cat3) instruction has both a ``(nopN)`` interpretation in addtion to 207the ``(rptN`)`` interpretation. 208 209An ``<override>`` in a bitset allows to redefine the display string, and/or 210field definitions from the default case. If the override's expr(ession) 211evaluates to non-zero, ``<display>``, ``<field>``, and ``<derived>`` 212elements take precedence over what is defined in the toplevel of the 213bitset (ie. the default case). 214 215Expressions 216----------- 217 218Both ``<override>`` and ``<derived>`` fields make use of ``<expr>`` elements, 219either defined inline, or defined and named at the top level and referred to 220by name in multiple other places. An expression is a simple 'C' expression 221which can reference fields (including other derived fields) with the same 222``{FIELDNAME}`` syntax as display template strings. For example: 223 224.. code-block:: xml 225 226 <expr name="#cat2-cat3-nop-encoding"> 227 (({SRC1_R} != 0) || ({SRC2_R} != 0)) && ({REPEAT} == 0) 228 </expr> 229 230In the case of ``<override>`` elements, the override applies if the expression 231evaluates to non-zero. In the case of ``<derived>`` fields, the expression 232evaluates to the value of the derived field. 233 234Encoding 235-------- 236 237To facilitate instruction encoding, ``<encode>`` elements can be provided 238to teach the generated instruction packing code how to map from data structures 239representing the IR to fields. For example: 240 241.. code-block:: xml 242 243 <bitset name="#instruction" size="64"> 244 <doc> 245 Encoding of an ir3 instruction. All instructions are 64b. 246 </doc> 247 <gen min="300"/> 248 <encode type="struct ir3_instruction *" case-prefix="OPC_"> 249 <!-- 250 Define mapping from encode src to individual fields, 251 which are common across all instruction categories 252 at the root instruction level 253 254 Not all of these apply to all instructions, but we 255 can define mappings here for anything that is used 256 in more than one instruction category. For things 257 that are specific to a single instruction category, 258 mappings should be defined at that level instead. 259 --> 260 <map name="DST">src->regs[0]</map> 261 <map name="SRC1">src->regs[1]</map> 262 <map name="SRC2">src->regs[2]</map> 263 <map name="SRC3">src->regs[3]</map> 264 <map name="REPEAT">src->repeat</map> 265 <map name="SS">!!(src->flags & IR3_INSTR_SS)</map> 266 <map name="JP">!!(src->flags & IR3_INSTR_JP)</map> 267 <map name="SY">!!(src->flags & IR3_INSTR_SY)</map> 268 <map name="UL">!!(src->flags & IR3_INSTR_UL)</map> 269 <map name="EQ">0</map> <!-- We don't use this (yet) --> 270 <map name="SAT">!!(src->flags & IR3_INSTR_SAT)</map> 271 </encode> 272 </bitset> 273 274The ``type`` attribute specifies that the input to encoding an instruction 275is a ``struct ir3_instruction *``. In the case of bitset hierarchies with 276multiple possible leaf nodes, a ``case-prefix`` attribute should be supplied 277along with a function that maps the bitset encode source to an enum value 278with the specified prefix prepended to uppercase'd leaf node name. Ie. in 279this case, "add.f" becomes ``OPC_ADD_F``. 280 281Individual ``<map>`` elements teach the encoder how to map from the encode 282source to fields in the encoded instruction. 283