hexagon/idef-parser/README.rst

1 Hexagon ISA instruction definitions to tinycode generator compiler
2 ------------------------------------------------------------------
4 idef-parser is a small compiler able to translate the Hexagon ISA description
8 -------------------
10 To better understand the scope of the idef-parser, we'll explore an applicative
11 example. Let's start by one of the simplest Hexagon instruction: the ``add``.
22 idef-parser will compile the above code into the following code:
48 instruction belongs, in this case ``A2`` corresponds to the Hexagon
57 -  Fill in the output function signature with the correct TCGv registers
58 -  Fill in the output function signature with the immediate integers
59 -  Keep track of which registers, among the declared one, have been
73 idef-parser has to handle a lower number of computation primitives.
105 ------------
107 Before moving on to the structure of idef-parser itself, let us spend some words
116 which takes instruction semantics in ``semantics_generated.pyinc`` to C-like
141 These macros are defined in ``idef-parser/macros.h.inc`` and the step is
158 idef-parser later on.
161 ----------------
163 The idef-parser is built using the ``flex`` and ``bison``.
167 ``idef-parser.lex`` source file. The flex-generated scanner takes care also to
173 description contained in the ``idef-parser.y`` file. The generated parser
174 executes the ``main`` function at the end of the ``idef-parser.y`` file, which
180 flex-generated code, and reads the input file returning the next scanned token.
183 ``idef-parser.y`` file to build a unique syntactic tree, according to the
186 The grammar describes the whole file which contains the Hexagon instruction
231     ----------------------------------------
242 bracket-enclosed list of statements, a ``';'``, which is a ``nop`` instruction,
250 ``PdV``, ``CsV``, and other idiomatic register names from Hexagon, are
256 refer to Hexagon registers such as the program counter, stack pointer, and frame
266     #define fABS(A) (((A) < 0) ? (-(A)) : (A))
269 in ``idef-parser/macros.h.inc`` and as such is not expanded and kept as a "call"
273 example above, for more information see ``idef-parser/idef-parser.lex``.
275 Finally, in mapping these input expressions to tinycode generators, idef-parser
290     int var1;           ->      TCGv_i32 var1 = tcg_temp_new_i32();
292     int var2 = 0;       ->      TCGv_i32 var1 = tcg_temp_new_i32();
301     type                        bit-width    signedness
302     ----------------------------------------------------------
326     size[1,2,4,8][s,u]_t        8-64         signed or unsigned
328 In idef-parser, variable names are matched by a generic ``VARID`` token,
330 idef-parser calls ``gen_varid_allocate`` with the ``VARID`` token to save the
339 idef-parser features a simple type system which is used to correctly implement
364 the appropriate compile-time or run-time emission of operations to perform the
386 do not reproduce short-circuiting of the ``&&`` operator, and use of the ``||``
389 like C-style ternary expressions:
410 All the helper functions in ``idef-parser.y`` carry two fixed parameters, which
420 ---------
422 Developing the idef-parser can lead to two types of errors: compile-time errors
425 Compile-time errors in Bison-generated parsers are usually due to conflicts in
430 For solving conflicts you need a basic understanding of `shift-reduce conflicts
432 and `reduce-reduce conflicts
436 ``-Wcex`` option to Bison. In general shift/reduce conflicts are solved by
441 Run-time errors can be divided between lexing and parsing errors, lexing errors
446 idef-parser features a fancy parsing error reporting scheme, which for each
453 -  not-emitted
461 -  emitted
467    which boil down to errors in the idef-parser type system.
469 -  compiled
477    multi-threaded test fail, fixing all the other tests will be the easier
478    option, hoping that the multi-threaded one will be indirectly fixed.
483 -  tests-passed
495    sudo unshare -p sudo -u <USER> bash -c \
496    'env -i <qemu-hexagon full path> -d cpu <TEST>'
528 For example, let's run the ``check-tcg`` tests
532     make check-tcg TIMEOUT=1200 \
533                    DOCKER_IMAGE=debian-hexagon-cross \
535                    DOCKER_CROSS_CC_GUEST=hexagon-unknown-linux-musl-clang
541 options ``-d in_asm,cpu`` of QEMU to inspect the Hexagon instructions being run,
547     meson configure -Dhexagon_idef_parser=false
549 will disable the idef-parser for all instructions and fallback on manual
551 gives us ``qemu-hexagon`` which passes all tests. If ``qemu-hexagon-buggy`` is
557     ./qemu-hexagon-buggy -d in_asm,cpu float_convs &> out_buggy
558     ./qemu-hexagon       -d in_asm,cpu float_convs &> out_working
560 Looking at ``diff -u out_buggy out_working`` shows us that the CPU state begins
565     @@ -138,7 +138,7 @@
569     -  r1 = 0x00042108
580     116 |  ----------------
592 Importantly, we see some Hexagon assembly followed by a dump of the CPU state,
600     54 |  ----------------
619 Remember, the instructions on lines 56-65 are ran on the CPU state shown below
634 ``./qemu-heaxgon -d op,in_asm float_conv`` where we find for the following
635 tinycode for the Hexagon ``add`` instruction
639    ---- 00021094
649 ----------------------------------
651 The main limitation of the current parser is given by the syntax-driven nature
652 of the Bison-generated parsers. This has the severe implication of only being
668 Instead we pre-process that statement, making it become:
698 consequence of the syntax-driven nature of the parser. In fact when we parse the
706 of the scanner, the parser, and a partial re-design of the type system, allowing
713 could be furtherly optimized, overcoming the limitations of the syntax-driven