target/ppc: Fix slbia TLB invalidation gap
[qemu.git] / docs / devel / decodetree.rst
1 ========================
2 Decodetree Specification
3 ========================
4
5 A *decodetree* is built from instruction *patterns*.  A pattern may
6 represent a single architectural instruction or a group of same, depending
7 on what is convenient for further processing.
8
9 Each pattern has both *fixedbits* and *fixedmask*, the combination of which
10 describes the condition under which the pattern is matched::
11
12   (insn & fixedmask) == fixedbits
13
14 Each pattern may have *fields*, which are extracted from the insn and
15 passed along to the translator.  Examples of such are registers,
16 immediates, and sub-opcodes.
17
18 In support of patterns, one may declare *fields*, *argument sets*, and
19 *formats*, each of which may be re-used to simplify further definitions.
20
21 Fields
22 ======
23
24 Syntax::
25
26   field_def     := '%' identifier ( unnamed_field )* ( !function=identifier )?
27   unnamed_field := number ':' ( 's' ) number
28
29 For *unnamed_field*, the first number is the least-significant bit position
30 of the field and the second number is the length of the field.  If the 's' is
31 present, the field is considered signed.  If multiple ``unnamed_fields`` are
32 present, they are concatenated.  In this way one can define disjoint fields.
33
34 If ``!function`` is specified, the concatenated result is passed through the
35 named function, taking and returning an integral value.
36
37 One may use ``!function`` with zero ``unnamed_fields``.  This case is called
38 a *parameter*, and the named function is only passed the ``DisasContext``
39 and returns an integral value extracted from there.
40
41 A field with no ``unnamed_fields`` and no ``!function`` is in error.
42
43 FIXME: the fields of the structure into which this result will be stored
44 is restricted to ``int``.  Which means that we cannot expand 64-bit items.
45
46 Field examples:
47
48 +---------------------------+---------------------------------------------+
49 | Input                     | Generated code                              |
50 +===========================+=============================================+
51 | %disp   0:s16             | sextract(i, 0, 16)                          |
52 +---------------------------+---------------------------------------------+
53 | %imm9   16:6 10:3         | extract(i, 16, 6) << 3 | extract(i, 10, 3)  |
54 +---------------------------+---------------------------------------------+
55 | %disp12 0:s1 1:1 2:10     | sextract(i, 0, 1) << 11 |                   |
56 |                           |    extract(i, 1, 1) << 10 |                 |
57 |                           |    extract(i, 2, 10)                        |
58 +---------------------------+---------------------------------------------+
59 | %shimm8 5:s8 13:1         | expand_shimm8(sextract(i, 5, 8) << 1 |      |
60 |   !function=expand_shimm8 |               extract(i, 13, 1))            |
61 +---------------------------+---------------------------------------------+
62
63 Argument Sets
64 =============
65
66 Syntax::
67
68   args_def    := '&' identifier ( args_elt )+ ( !extern )?
69   args_elt    := identifier
70
71 Each *args_elt* defines an argument within the argument set.
72 Each argument set will be rendered as a C structure "arg_$name"
73 with each of the fields being one of the member arguments.
74
75 If ``!extern`` is specified, the backing structure is assumed
76 to have been already declared, typically via a second decoder.
77
78 Argument sets are useful when one wants to define helper functions
79 for the translator functions that can perform operations on a common
80 set of arguments.  This can ensure, for instance, that the ``AND``
81 pattern and the ``OR`` pattern put their operands into the same named
82 structure, so that a common ``gen_logic_insn`` may be able to handle
83 the operations common between the two.
84
85 Argument set examples::
86
87   &reg3       ra rb rc
88   &loadstore  reg base offset
89
90
91 Formats
92 =======
93
94 Syntax::
95
96   fmt_def      := '@' identifier ( fmt_elt )+
97   fmt_elt      := fixedbit_elt | field_elt | field_ref | args_ref
98   fixedbit_elt := [01.-]+
99   field_elt    := identifier ':' 's'? number
100   field_ref    := '%' identifier | identifier '=' '%' identifier
101   args_ref     := '&' identifier
102
103 Defining a format is a handy way to avoid replicating groups of fields
104 across many instruction patterns.
105
106 A *fixedbit_elt* describes a contiguous sequence of bits that must
107 be 1, 0, or don't care.  The difference between '.' and '-'
108 is that '.' means that the bit will be covered with a field or a
109 final 0 or 1 from the pattern, and '-' means that the bit is really
110 ignored by the cpu and will not be specified.
111
112 A *field_elt* describes a simple field only given a width; the position of
113 the field is implied by its position with respect to other *fixedbit_elt*
114 and *field_elt*.
115
116 If any *fixedbit_elt* or *field_elt* appear, then all bits must be defined.
117 Padding with a *fixedbit_elt* of all '.' is an easy way to accomplish that.
118
119 A *field_ref* incorporates a field by reference.  This is the only way to
120 add a complex field to a format.  A field may be renamed in the process
121 via assignment to another identifier.  This is intended to allow the
122 same argument set be used with disjoint named fields.
123
124 A single *args_ref* may specify an argument set to use for the format.
125 The set of fields in the format must be a subset of the arguments in
126 the argument set.  If an argument set is not specified, one will be
127 inferred from the set of fields.
128
129 It is recommended, but not required, that all *field_ref* and *args_ref*
130 appear at the end of the line, not interleaving with *fixedbit_elf* or
131 *field_elt*.
132
133 Format examples::
134
135   @opr    ...... ra:5 rb:5 ... 0 ....... rc:5
136   @opi    ...... ra:5 lit:8    1 ....... rc:5
137
138 Patterns
139 ========
140
141 Syntax::
142
143   pat_def      := identifier ( pat_elt )+
144   pat_elt      := fixedbit_elt | field_elt | field_ref | args_ref | fmt_ref | const_elt
145   fmt_ref      := '@' identifier
146   const_elt    := identifier '=' number
147
148 The *fixedbit_elt* and *field_elt* specifiers are unchanged from formats.
149 A pattern that does not specify a named format will have one inferred
150 from a referenced argument set (if present) and the set of fields.
151
152 A *const_elt* allows a argument to be set to a constant value.  This may
153 come in handy when fields overlap between patterns and one has to
154 include the values in the *fixedbit_elt* instead.
155
156 The decoder will call a translator function for each pattern matched.
157
158 Pattern examples::
159
160   addl_r   010000 ..... ..... .... 0000000 ..... @opr
161   addl_i   010000 ..... ..... .... 0000000 ..... @opi
162
163 which will, in part, invoke::
164
165   trans_addl_r(ctx, &arg_opr, insn)
166
167 and::
168
169   trans_addl_i(ctx, &arg_opi, insn)
170
171 Pattern Groups
172 ==============
173
174 Syntax::
175
176   group    := '{' ( pat_def | group )+ '}'
177
178 A *group* begins with a lone open-brace, with all subsequent lines
179 indented two spaces, and ending with a lone close-brace.  Groups
180 may be nested, increasing the required indentation of the lines
181 within the nested group to two spaces per nesting level.
182
183 Unlike ungrouped patterns, grouped patterns are allowed to overlap.
184 Conflicts are resolved by selecting the patterns in order.  If all
185 of the fixedbits for a pattern match, its translate function will
186 be called.  If the translate function returns false, then subsequent
187 patterns within the group will be matched.
188
189 The following example from PA-RISC shows specialization of the *or*
190 instruction::
191
192   {
193     {
194       nop   000010 ----- ----- 0000 001001 0 00000
195       copy  000010 00000 r1:5  0000 001001 0 rt:5
196     }
197     or      000010 rt2:5 r1:5  cf:4 001001 0 rt:5
198   }
199
200 When the *cf* field is zero, the instruction has no side effects,
201 and may be specialized.  When the *rt* field is zero, the output
202 is discarded and so the instruction has no effect.  When the *rt2*
203 field is zero, the operation is ``reg[rt] | 0`` and so encodes
204 the canonical register copy operation.
205
206 The output from the generator might look like::
207
208   switch (insn & 0xfc000fe0) {
209   case 0x08000240:
210     /* 000010.. ........ ....0010 010..... */
211     if ((insn & 0x0000f000) == 0x00000000) {
212         /* 000010.. ........ 00000010 010..... */
213         if ((insn & 0x0000001f) == 0x00000000) {
214             /* 000010.. ........ 00000010 01000000 */
215             extract_decode_Fmt_0(&u.f_decode0, insn);
216             if (trans_nop(ctx, &u.f_decode0)) return true;
217         }
218         if ((insn & 0x03e00000) == 0x00000000) {
219             /* 00001000 000..... 00000010 010..... */
220             extract_decode_Fmt_1(&u.f_decode1, insn);
221             if (trans_copy(ctx, &u.f_decode1)) return true;
222         }
223     }
224     extract_decode_Fmt_2(&u.f_decode2, insn);
225     if (trans_or(ctx, &u.f_decode2)) return true;
226     return false;
227   }