diff options
Diffstat (limited to 'llvm/docs/TableGen')
| -rw-r--r-- | llvm/docs/TableGen/BackGuide.rst | 24 | ||||
| -rw-r--r-- | llvm/docs/TableGen/index.rst | 44 |
2 files changed, 34 insertions, 34 deletions
diff --git a/llvm/docs/TableGen/BackGuide.rst b/llvm/docs/TableGen/BackGuide.rst index 83f8f470..7883d7c 100644 --- a/llvm/docs/TableGen/BackGuide.rst +++ b/llvm/docs/TableGen/BackGuide.rst @@ -17,7 +17,7 @@ information is coded in a declarative style involving classes and records, which are then processed by TableGen. The internalized records are passed on to various backends, which extract information from a subset of the records and generate an output file. These output files are typically ``.inc`` files -for C++, but may be any type of file that the backend developer needs. +for C++, but they may be any type of file that the backend developer needs. This document is a guide to writing a backend for TableGen. It is not a complete reference manual, but rather a guide to using the facilities @@ -114,7 +114,7 @@ The ``Record`` class provides many useful functions. superclasses. * Functions to get a particular field value by specifying its name in various - forms, and returning its value in various forms + forms and returning its value in various forms (see `Getting Record Names and Fields`_). * Boolean functions to check the various attributes of the record. @@ -301,7 +301,7 @@ The ``BitInit`` class is a subclass of ``TypedInit``. Its instances represent the possible values of a bit: 0 or 1. It includes a data member that contains the bit. -*All* of the classes derived from ``TypedInit`` provide the following functions. +*All* of the classes derived from ``TypedInit`` provide the following functions: * A static function named ``get()`` that returns an ``Init`` representing the specified value(s). In the case of ``BitInit``, ``get(true)`` returns @@ -334,7 +334,7 @@ The class provides the following additional functions. ~~~~~~~~~~~ The ``DagInit`` class is a subclass of ``TypedInit``. Its instances -represent the possible direct acyclic graphs (``dag``). +represent the possible directed acyclic graphs (``dag``). The class includes a pointer to an ``Init`` for the DAG operator and a pointer to a ``StringInit`` for the operator name. It includes the count of @@ -357,7 +357,7 @@ The class provides many additional functions: * Functions to get the operands, both individually and together. * Functions to determine whether there are any names and to - get the number of names + get the number of names. * Functions to get the names, both individually and together. @@ -410,7 +410,7 @@ The class provides the usual ``get()`` and ``getValues()`` functions. The latter function returns an ``ArrayRef`` of the vector of pointers to ``Init`` instances. -The class provides these additional functions. +The class provides these additional functions: * A function to get the element type. @@ -461,7 +461,7 @@ The Backend Skeleton ==================== The file ``TableGenBackendSkeleton.cpp`` provides a skeleton C++ translation -unit for writing a new TableGen backend. Here are a few notes on the file. +unit for writing a new TableGen backend. Here are a few notes on the file: * The list of includes is the minimal list required by most backends. @@ -484,7 +484,7 @@ unit for writing a new TableGen backend. Here are a few notes on the file. * The ``run`` function should use the ``emitSourceFileHeader`` helper function to include a standard header in the emitted file. -* Register the class or the function as the command line option +* Register the class or the function as the command-line option with ``llvm/TableGen/TableGenBackend.h``. * Use ``llvm::TableGen::Emitter::OptClass<AddressModesEmitter>`` @@ -516,7 +516,7 @@ If you need to iterate over all the class records: ... } -``ClassPair.second`` gets the class's ``unique_ptr``, then ``.get()`` gets the +``ClassPair.second`` gets the class's ``unique_ptr``, and then ``.get()`` gets the class ``Record`` itself. @@ -612,7 +612,7 @@ Getting Record Superclasses The ``Record`` class provides a function to obtain the direct superclasses of a record. It is named ``getDirectSuperClasses`` and returns an -``ArrayRef`` of an array of ``std::pair`` pairs. Each pair consists of a +``ArrayRef`` of an array of ``std::pair`` instances. Each pair consists of a pointer to the ``Record`` instance for a superclass record and an instance of the ``SMRange`` class. The range indicates the source file locations of the beginning and end of the class definition. @@ -630,7 +630,7 @@ then iterates over the pairs in the returned array. The ``Record`` class also provides a function, ``getSuperClasses``, to return a vector of *all* superclasses of a record. The superclasses are in -post-order: the order in which the superclasses were visited while copying +postorder: the order in which the superclasses were visited while copying their fields into the record. Emitting Text to the Output Stream @@ -752,7 +752,7 @@ The ``PrintDetailedRecords`` Backend The TableGen command option ``--print-detailed-records`` invokes a backend that prints all the global variables, classes, and records defined in the source files. The format of the output is *not* guaranteed to be constant -over time. The output looks like this. +over time. The output looks like this: .. code-block:: text diff --git a/llvm/docs/TableGen/index.rst b/llvm/docs/TableGen/index.rst index e916c15..e334b2e 100644 --- a/llvm/docs/TableGen/index.rst +++ b/llvm/docs/TableGen/index.rst @@ -20,7 +20,7 @@ domain-specific information. Because there may be a large number of these records, it is specifically designed to allow writing flexible descriptions and for common features of these records to be factored out. This reduces the amount of duplication in the description, reduces the chance of error, and makes -it easier to structure domain specific information. +it easier to structure domain-specific information. The TableGen front end parses a file, instantiates the declarations, and hands the result off to a domain-specific `backend`_ for processing. See @@ -44,8 +44,8 @@ distribution, respectively. The TableGen program ==================== -TableGen files are interpreted by the TableGen program: `llvm-tblgen` available -on your build directory under `bin`. It is not installed in the system (or where +TableGen files are interpreted by the TableGen program: ``llvm-tblgen`` available +in your build directory under ``bin``. It is not installed in the system (or where your sysroot is set to), since it has no use beyond LLVM's build process. Running TableGen @@ -86,7 +86,7 @@ the `-dump-json` option. If you plan to use TableGen, you will most likely have to write a `backend`_ that extracts the information specific to what you need and formats it in the -appropriate way. You can do this by extending TableGen itself in C++, or by +appropriate way. You can do this by extending TableGen itself in C++ or by writing a script in any language that can consume the JSON output. Example @@ -152,7 +152,7 @@ of the x86 architecture. ``def ADD32rr`` defines a record named ``ADD32rr``, and the comment at the end of the line indicates the superclasses of the definition. The body of the record contains all of the data that TableGen assembled for the record, indicating that the instruction is part of -the "X86" namespace, the pattern indicating how the instruction is selected by +the ``X86`` namespace, the pattern indicating how the instruction is selected by the code generator, that it is a two-address instruction, has a particular encoding, etc. The contents and semantics of the information in the record are specific to the needs of the X86 backend, and are only shown as an example. @@ -175,13 +175,13 @@ TableGen, all of the information was derived from the following definition: This definition makes use of the custom class ``I`` (extended from the custom class ``X86Inst``), which is defined in the X86-specific TableGen file, to factor out the common features that instructions of its class share. A key -feature of TableGen is that it allows the end-user to define the abstractions +feature of TableGen is that it allows the end user to define the abstractions they prefer to use when describing their information. Syntax ====== -TableGen has a syntax that is loosely based on C++ templates, with built-in +TableGen has a syntax loosely based on C++ templates, with built-in types and specification. In addition, TableGen's syntax introduces some automation concepts like multiclass, foreach, let, etc. @@ -193,41 +193,41 @@ which are considered 'records'. **TableGen records** have a unique name, a list of values, and a list of superclasses. The list of values is the main data that TableGen builds for each -record; it is this that holds the domain specific information for the +record; it is this that holds the domain-specific information for the application. The interpretation of this data is left to a specific `backend`_, -but the structure and format rules are taken care of and are fixed by +but the structure and format rules are taken care of and fixed by TableGen. **TableGen definitions** are the concrete form of 'records'. These generally do -not have any undefined values, and are marked with the '``def``' keyword. +not have any undefined values and are marked with the '``def``' keyword. .. code-block:: text def FeatureFPARMv8 : SubtargetFeature<"fp-armv8", "HasFPARMv8", "true", "Enable ARMv8 FP">; -In this example, FeatureFPARMv8 is ``SubtargetFeature`` record initialised +In this example, ``FeatureFPARMv8`` is ``SubtargetFeature`` record initialised with some values. The names of the classes are defined via the -keyword `class` either on the same file or some other included. Most target +keyword `class` either in the same file or some other included. Most target TableGen files include the generic ones in ``include/llvm/Target``. **TableGen classes** are abstract records that are used to build and describe other records. These classes allow the end-user to build abstractions for -either the domain they are targeting (such as "Register", "RegisterClass", and -"Instruction" in the LLVM code generator) or for the implementor to help factor -out common properties of records (such as "FPInst", which is used to represent +either the domain they are targeting (such as ``Register``, ``RegisterClass``, and +``Instruction`` in the LLVM code generator) or for the implementor to help factor +out common properties of records (such as ``FPInst``, which is used to represent floating point instructions in the X86 backend). TableGen keeps track of all of the classes that are used to build up a definition, so the backend can find all -definitions of a particular class, such as "Instruction". +definitions of a particular class, such as ``Instruction``. .. code-block:: text class ProcNoItin<string Name, list<SubtargetFeature> Features> : Processor<Name, NoItineraries, Features>; -Here, the class ProcNoItin, receiving parameters `Name` of type `string` and -a list of target features is specializing the class Processor by passing the -arguments down as well as hard-coding NoItineraries. +Here, the class ``ProcNoItin``, receiving parameters ``Name`` of type ``string`` and +a list of target features is specializing the class ``Processor`` by passing the +arguments down as well as hard-coding ``NoItineraries``. **TableGen multiclasses** are groups of abstract records that are instantiated all at once. Each instantiation can result in multiple TableGen definitions. @@ -295,8 +295,8 @@ TableGen Deficiencies Despite being very generic, TableGen has some deficiencies that have been pointed out numerous times. The common theme is that, while TableGen allows -you to build domain specific languages, the final languages that you create -lack the power of other DSLs, which in turn increase considerably the size +you to build domain-specific languages, the final languages that you create +lack the power of other DSLs, which in turn considerably increases the size and complexity of TableGen files. At the same time, TableGen allows you to create virtually any meaning of @@ -305,6 +305,6 @@ design and make it very hard for newcomers to understand the evil TableGen file. There are some in favor of extending the semantics even more, but making sure -backends adhere to strict rules. Others are suggesting we should move to less, +backends adhere to strict rules. Others suggest moving to fewer, more powerful DSLs designed with specific purposes, or even reusing existing DSLs. |