Index: llvm/docs/TableGen/BackGuide.rst =================================================================== --- llvm/docs/TableGen/BackGuide.rst +++ llvm/docs/TableGen/BackGuide.rst @@ -52,14 +52,7 @@ There are two maps in the recordkeeper, one for classes and one for records (the latter often referred to as *defs*). Each map maps the class or record name to an instance of the ``Record`` class (see `Record`_), which contains -all the information about that class or record. The ``RecordKeeper`` class -defines a type that must be used to declare these maps if they are requested -directly. - -.. code-block:: text - - using RecordMap = std::map, - std::less<>>; +all the information about that class or record. In addition to the two maps, the ``RecordKeeper`` instance contains: @@ -562,7 +555,7 @@ * ``getDefs()`` returns a ``RecordMap`` reference for all the concrete records. -* ``getDef(``\ *name*\ ``)`` return a ``Record`` reference for the named +* ``getDef(``\ *name*\ ``)`` returns a ``Record`` reference for the named concrete record. * ``getAllDerivedDefinitions(``\ *classname*\ ``)`` returns a vector of @@ -701,7 +694,7 @@ defined through a sequence of multiclasses. Because of this, it can be difficult for backends to report clear error messages with accurate source file locations. To make error reporting easier, five error reporting -functions are provided, each with four overloads. [all combinations to come] +functions are provided, each with four overloads. * ``PrintWarning`` prints a message tagged as a warning. @@ -827,4 +820,4 @@ parentheses. Each field is shown with its value and the source location at which it was set. The ``defm`` sequence gives the locations of the ``defm`` statements that -were involved in generating the record, in the order they were invoked. \ No newline at end of file +were involved in generating the record, in the order they were invoked. Index: llvm/docs/TableGen/ProgRef.rst =================================================================== --- llvm/docs/TableGen/ProgRef.rst +++ llvm/docs/TableGen/ProgRef.rst @@ -444,8 +444,11 @@ This form creates a new anonymous record definition (as would be created by an unnamed ``def`` inheriting from the given class with the given template -arguments; see `def`_) and the value is that record. (A field of the record can be -obtained using a suffix; see `Suffixed Values`_.) +arguments; see `def`_) and the value is that record. A field of the record can be +obtained using a suffix; see `Suffixed Values`_. + +Invoking a class in this manner can provide a simple subroutine facility. +See `Using Classes as Subroutines`_ for more information. .. productionlist:: SimpleValue8: `BangOperator` ["<" `Type` ">"] "(" `ValueListNE` ")" @@ -541,7 +544,7 @@ .. _NAME: -Every class has an implicit template argument named ``NAME`` (uppercse), +Every class has an implicit template argument named ``NAME`` (uppercase), which is bound to the name of the :token:`Def` or :token:`Defm` inheriting the class. The value of ``NAME`` is undefined if the class is inherited by an anonymous record. @@ -1252,7 +1255,7 @@ A variable named ``V`` in an inner scope shadows (hides) any variables ``V`` in outer scopes. In particular, ``V`` in a record body shadows a global ``V``, and ``V`` in a ``foreach`` statement list shadows any ``V`` in -surrounding global or record scopes. +surrounding record or global scopes. Variables defined in a ``foreach`` go out of scope at the end of each loop iteration, so their value in one iteration is not available in @@ -1288,7 +1291,6 @@ 6. Add the record to the master record list. - Because references between fields are resolved (step 5) after ``let`` bindings are applied (step 3), the ``let`` statement has unusual power. For example: @@ -1329,6 +1331,52 @@ 1)`` is resolved. Use this power wisely. +Using Classes as Subroutines +============================ + +As described in `Simple values`_, a class can be invoked in an expression +and passed template arguments. This causes TableGen to create a new anonymous +record inheriting from that class. As usual, the record receives all the +fields defined in the class. + +This feature can be employed as a simple subroutine facility. The class can +use the template arguments to define various variables and fields, which end +up in the anonymous record. Those fields can then be retrieved in the +expression invoking the class as follows. Assume that the field ``ret`` +contains the final value of the subroutine. + +.. code-block:: text + + int Result = ... CalcValue.ret ...; + +The ``CalcValue`` class is invoked with the template argument ``arg``. It +calculates a value for the ``ret`` field, which is then retrieved at the +"point of call" in the initialization for the Result field. The anonymous +record created in this example serves no other purpose than to carry the +result value. + +Here is a practical example. The class ``isValidSize`` determines whether a +specified number of bytes represents a valid data size. The bit ``ret`` is +set appropriately. The field ``ValidSize`` obtains its initial value by +invoking ``isValidSize`` with the data size and retrieving the ``ret`` field +from the resulting anonymous record. + +.. code-block:: text + + class isValidSize { + bit ret = !cond(!eq(size, 1): 1, + !eq(size, 2): 1, + !eq(size, 4): 1, + !eq(size, 8): 1, + !eq(size, 16): 1, + 1: 0); + } + + def Data1 { + int Size = ...; + bit ValidSize = isValidSize.ret; + } + Preprocessing Facilities ======================== @@ -1372,8 +1420,8 @@ the macro name is defined (``#ifdef``) or undefined (``#ifndef``), then the source code between the directive and the corresponding ``#else`` or ``#endif`` is processed. If the test fails but there is an ``#else`` -portion, the source code between the ``#else`` and the ``#endif`` is -processed. If the test fails and there is no ``#else`` portion, then no +clause, the source code between the ``#else`` and the ``#endif`` is +processed. If the test fails and there is no ``#else`` clause, then no source code in the test region is processed. Test regions may be nested, but they must be properly nested. A region @@ -1381,7 +1429,7 @@ ``#endif`` in the same file. A :token:`MacroName` may be defined externally using the ``-D`` option on the -``llvm-tblgen`` command line:: +``xxx-tblgen`` command line:: llvm-tblgen self-reference.td -Dmacro1 -Dmacro3