| ======================== |
| Decodetree Specification |
| ======================== |
| |
| A *decodetree* is built from instruction *patterns*. A pattern may |
| represent a single architectural instruction or a group of same, depending |
| on what is convenient for further processing. |
| |
| Each pattern has both *fixedbits* and *fixedmask*, the combination of which |
| describes the condition under which the pattern is matched:: |
| |
| (insn & fixedmask) == fixedbits |
| |
| Each pattern may have *fields*, which are extracted from the insn and |
| passed along to the translator. Examples of such are registers, |
| immediates, and sub-opcodes. |
| |
| In support of patterns, one may declare *fields*, *argument sets*, and |
| *formats*, each of which may be re-used to simplify further definitions. |
| |
| Fields |
| ====== |
| |
| Syntax:: |
| |
| field_def := '%' identifier ( unnamed_field )+ ( !function=identifier )? |
| unnamed_field := number ':' ( 's' ) number |
| |
| For *unnamed_field*, the first number is the least-significant bit position |
| of the field and the second number is the length of the field. If the 's' is |
| present, the field is considered signed. If multiple ``unnamed_fields`` are |
| present, they are concatenated. In this way one can define disjoint fields. |
| |
| If ``!function`` is specified, the concatenated result is passed through the |
| named function, taking and returning an integral value. |
| |
| FIXME: the fields of the structure into which this result will be stored |
| is restricted to ``int``. Which means that we cannot expand 64-bit items. |
| |
| Field examples: |
| |
| +---------------------------+---------------------------------------------+ |
| | Input | Generated code | |
| +===========================+=============================================+ |
| | %disp 0:s16 | sextract(i, 0, 16) | |
| +---------------------------+---------------------------------------------+ |
| | %imm9 16:6 10:3 | extract(i, 16, 6) << 3 | extract(i, 10, 3) | |
| +---------------------------+---------------------------------------------+ |
| | %disp12 0:s1 1:1 2:10 | sextract(i, 0, 1) << 11 | | |
| | | extract(i, 1, 1) << 10 | | |
| | | extract(i, 2, 10) | |
| +---------------------------+---------------------------------------------+ |
| | %shimm8 5:s8 13:1 | expand_shimm8(sextract(i, 5, 8) << 1 | | |
| | !function=expand_shimm8 | extract(i, 13, 1)) | |
| +---------------------------+---------------------------------------------+ |
| |
| Argument Sets |
| ============= |
| |
| Syntax:: |
| |
| args_def := '&' identifier ( args_elt )+ ( !extern )? |
| args_elt := identifier |
| |
| Each *args_elt* defines an argument within the argument set. |
| Each argument set will be rendered as a C structure "arg_$name" |
| with each of the fields being one of the member arguments. |
| |
| If ``!extern`` is specified, the backing structure is assumed |
| to have been already declared, typically via a second decoder. |
| |
| Argument sets are useful when one wants to define helper functions |
| for the translator functions that can perform operations on a common |
| set of arguments. This can ensure, for instance, that the ``AND`` |
| pattern and the ``OR`` pattern put their operands into the same named |
| structure, so that a common ``gen_logic_insn`` may be able to handle |
| the operations common between the two. |
| |
| Argument set examples:: |
| |
| ®3 ra rb rc |
| &loadstore reg base offset |
| |
| |
| Formats |
| ======= |
| |
| Syntax:: |
| |
| fmt_def := '@' identifier ( fmt_elt )+ |
| fmt_elt := fixedbit_elt | field_elt | field_ref | args_ref |
| fixedbit_elt := [01.-]+ |
| field_elt := identifier ':' 's'? number |
| field_ref := '%' identifier | identifier '=' '%' identifier |
| args_ref := '&' identifier |
| |
| Defining a format is a handy way to avoid replicating groups of fields |
| across many instruction patterns. |
| |
| A *fixedbit_elt* describes a contiguous sequence of bits that must |
| be 1, 0, or don't care. The difference between '.' and '-' |
| is that '.' means that the bit will be covered with a field or a |
| final 0 or 1 from the pattern, and '-' means that the bit is really |
| ignored by the cpu and will not be specified. |
| |
| A *field_elt* describes a simple field only given a width; the position of |
| the field is implied by its position with respect to other *fixedbit_elt* |
| and *field_elt*. |
| |
| If any *fixedbit_elt* or *field_elt* appear, then all bits must be defined. |
| Padding with a *fixedbit_elt* of all '.' is an easy way to accomplish that. |
| |
| A *field_ref* incorporates a field by reference. This is the only way to |
| add a complex field to a format. A field may be renamed in the process |
| via assignment to another identifier. This is intended to allow the |
| same argument set be used with disjoint named fields. |
| |
| A single *args_ref* may specify an argument set to use for the format. |
| The set of fields in the format must be a subset of the arguments in |
| the argument set. If an argument set is not specified, one will be |
| inferred from the set of fields. |
| |
| It is recommended, but not required, that all *field_ref* and *args_ref* |
| appear at the end of the line, not interleaving with *fixedbit_elf* or |
| *field_elt*. |
| |
| Format examples:: |
| |
| @opr ...... ra:5 rb:5 ... 0 ....... rc:5 |
| @opi ...... ra:5 lit:8 1 ....... rc:5 |
| |
| Patterns |
| ======== |
| |
| Syntax:: |
| |
| pat_def := identifier ( pat_elt )+ |
| pat_elt := fixedbit_elt | field_elt | field_ref | args_ref | fmt_ref | const_elt |
| fmt_ref := '@' identifier |
| const_elt := identifier '=' number |
| |
| The *fixedbit_elt* and *field_elt* specifiers are unchanged from formats. |
| A pattern that does not specify a named format will have one inferred |
| from a referenced argument set (if present) and the set of fields. |
| |
| A *const_elt* allows a argument to be set to a constant value. This may |
| come in handy when fields overlap between patterns and one has to |
| include the values in the *fixedbit_elt* instead. |
| |
| The decoder will call a translator function for each pattern matched. |
| |
| Pattern examples:: |
| |
| addl_r 010000 ..... ..... .... 0000000 ..... @opr |
| addl_i 010000 ..... ..... .... 0000000 ..... @opi |
| |
| which will, in part, invoke:: |
| |
| trans_addl_r(ctx, &arg_opr, insn) |
| |
| and:: |
| |
| trans_addl_i(ctx, &arg_opi, insn) |
| |
| Pattern Groups |
| ============== |
| |
| Syntax:: |
| |
| group := '{' ( pat_def | group )+ '}' |
| |
| A *group* begins with a lone open-brace, with all subsequent lines |
| indented two spaces, and ending with a lone close-brace. Groups |
| may be nested, increasing the required indentation of the lines |
| within the nested group to two spaces per nesting level. |
| |
| Unlike ungrouped patterns, grouped patterns are allowed to overlap. |
| Conflicts are resolved by selecting the patterns in order. If all |
| of the fixedbits for a pattern match, its translate function will |
| be called. If the translate function returns false, then subsequent |
| patterns within the group will be matched. |
| |
| The following example from PA-RISC shows specialization of the *or* |
| instruction:: |
| |
| { |
| { |
| nop 000010 ----- ----- 0000 001001 0 00000 |
| copy 000010 00000 r1:5 0000 001001 0 rt:5 |
| } |
| or 000010 rt2:5 r1:5 cf:4 001001 0 rt:5 |
| } |
| |
| When the *cf* field is zero, the instruction has no side effects, |
| and may be specialized. When the *rt* field is zero, the output |
| is discarded and so the instruction has no effect. When the *rt2* |
| field is zero, the operation is ``reg[rt] | 0`` and so encodes |
| the canonical register copy operation. |
| |
| The output from the generator might look like:: |
| |
| switch (insn & 0xfc000fe0) { |
| case 0x08000240: |
| /* 000010.. ........ ....0010 010..... */ |
| if ((insn & 0x0000f000) == 0x00000000) { |
| /* 000010.. ........ 00000010 010..... */ |
| if ((insn & 0x0000001f) == 0x00000000) { |
| /* 000010.. ........ 00000010 01000000 */ |
| extract_decode_Fmt_0(&u.f_decode0, insn); |
| if (trans_nop(ctx, &u.f_decode0)) return true; |
| } |
| if ((insn & 0x03e00000) == 0x00000000) { |
| /* 00001000 000..... 00000010 010..... */ |
| extract_decode_Fmt_1(&u.f_decode1, insn); |
| if (trans_copy(ctx, &u.f_decode1)) return true; |
| } |
| } |
| extract_decode_Fmt_2(&u.f_decode2, insn); |
| if (trans_or(ctx, &u.f_decode2)) return true; |
| return false; |
| } |
