| 1 |
================= |
| 2 |
TableGen BackEnds |
| 3 |
================= |
| 4 |
|
| 5 |
.. contents:: |
| 6 |
:local: |
| 7 |
|
| 8 |
Introduction |
| 9 |
============ |
| 10 |
|
| 11 |
TableGen backends are at the core of TableGen's functionality. The source |
| 12 |
files provide the classes and records that are parsed and end up as a |
| 13 |
collection of record instances, but it's up to the backend to interpret and |
| 14 |
print the records in a way that is meaningful to the user (normally a C++ |
| 15 |
include file or a textual list of warnings, options, and error messages). |
| 16 |
|
| 17 |
TableGen is used by both LLVM, Clang, and MLIR with very different goals. |
| 18 |
LLVM uses it as a way to automate the generation of massive amounts of |
| 19 |
information regarding instructions, schedules, cores, and architecture |
| 20 |
features. Some backends generate output that is consumed by more than one |
| 21 |
source file, so they need to be created in a way that makes it is easy for |
| 22 |
preprocessor tricks to be used. Some backends can also print C++ code |
| 23 |
structures, so that they can be directly included as-is. |
| 24 |
|
| 25 |
Clang, on the other hand, uses it mainly for diagnostic messages (errors, |
| 26 |
warnings, tips) and attributes, so more on the textual end of the scale. |
| 27 |
|
| 28 |
MLIR uses TableGen to define operations, operation dialects, and operation |
| 29 |
traits. |
| 30 |
|
| 31 |
See the :doc:`TableGen Programmer's Reference <./ProgRef>` for an in-depth |
| 32 |
description of TableGen, and the :doc:`TableGen Backend Developer's Guide |
| 33 |
<./BackGuide>` for a guide to writing a new backend. |
| 34 |
|
| 35 |
LLVM BackEnds |
| 36 |
============= |
| 37 |
|
| 38 |
.. warning:: |
| 39 |
This portion is incomplete. Each section below needs three subsections: |
| 40 |
description of its purpose with a list of users, output generated from |
| 41 |
generic input, and finally why it needed a new backend (in case there's |
| 42 |
something similar). |
| 43 |
|
| 44 |
Overall, each backend will take the same TableGen file type and transform into |
| 45 |
similar output for different targets/uses. There is an implicit contract between |
| 46 |
the TableGen files, the back-ends and their users. |
| 47 |
|
| 48 |
For instance, a global contract is that each back-end produces macro-guarded |
| 49 |
sections. Based on whether the file is included by a header or a source file, |
| 50 |
or even in which context of each file the include is being used, you have |
| 51 |
to define a macro just before including it, to get the right output: |
| 52 |
|
| 53 |
.. code-block:: c++ |
| 54 |
|
| 55 |
#define GET_REGINFO_TARGET_DESC |
| 56 |
#include "ARMGenRegisterInfo.inc" |
| 57 |
|
| 58 |
And just part of the generated file would be included. This is useful if |
| 59 |
you need the same information in multiple formats (instantiation, initialization, |
| 60 |
getter/setter functions, etc) from the same source TableGen file without having |
| 61 |
to re-compile the TableGen file multiple times. |
| 62 |
|
| 63 |
Sometimes, multiple macros might be defined before the same include file to |
| 64 |
output multiple blocks: |
| 65 |
|
| 66 |
.. code-block:: c++ |
| 67 |
|
| 68 |
#define GET_REGISTER_MATCHER |
| 69 |
#define GET_SUBTARGET_FEATURE_NAME |
| 70 |
#define GET_MATCHER_IMPLEMENTATION |
| 71 |
#include "ARMGenAsmMatcher.inc" |
| 72 |
|
| 73 |
The macros will be undef'd automatically as they're used, in the include file. |
| 74 |
|
| 75 |
On all LLVM back-ends, the ``llvm-tblgen`` binary will be executed on the root |
| 76 |
TableGen file ``<Target>.td``, which should include all others. This guarantees |
| 77 |
that all information needed is accessible, and that no duplication is needed |
| 78 |
in the TableGen files. |
| 79 |
|
| 80 |
CodeEmitter |
| 81 |
----------- |
| 82 |
|
| 83 |
**Purpose**: ``CodeEmitterGen`` uses the descriptions of instructions and their fields to |
| 84 |
construct an automated code emitter: a function that, given a ``MachineInstr``, |
| 85 |
returns the (currently, 32-bit unsigned) value of the instruction. |
| 86 |
|
| 87 |
**Output**: C++ code, implementing the target's CodeEmitter |
| 88 |
class by overriding the virtual functions as ``<Target>CodeEmitter::function()``. |
| 89 |
|
| 90 |
**Usage**: Used to include directly at the end of ``<Target>MCCodeEmitter.cpp``. |
| 91 |
|
| 92 |
RegisterInfo |
| 93 |
------------ |
| 94 |
|
| 95 |
**Purpose**: This tablegen backend is responsible for emitting a description of a target |
| 96 |
register file for a code generator. It uses instances of the Register, |
| 97 |
RegisterAliases, and RegisterClass classes to gather this information. |
| 98 |
|
| 99 |
**Output**: C++ code with enums and structures representing the register mappings, |
| 100 |
properties, masks, etc. |
| 101 |
|
| 102 |
**Usage**: Both on ``<Target>BaseRegisterInfo`` and ``<Target>MCTargetDesc`` (headers |
| 103 |
and source files) with macros defining in which they are for declaration vs. |
| 104 |
initialization issues. |
| 105 |
|
| 106 |
InstrInfo |
| 107 |
--------- |
| 108 |
|
| 109 |
**Purpose**: This tablegen backend is responsible for emitting a description of the target |
| 110 |
instruction set for the code generator. (what are the differences from CodeEmitter?) |
| 111 |
|
| 112 |
**Output**: C++ code with enums and structures representing the instruction mappings, |
| 113 |
properties, masks, etc. |
| 114 |
|
| 115 |
**Usage**: Both on ``<Target>BaseInstrInfo`` and ``<Target>MCTargetDesc`` (headers |
| 116 |
and source files) with macros defining in which they are for declaration vs. |
| 117 |
initialization issues. |
| 118 |
|
| 119 |
AsmWriter |
| 120 |
--------- |
| 121 |
|
| 122 |
**Purpose**: Emits an assembly printer for the current target. |
| 123 |
|
| 124 |
**Output**: Implementation of ``<Target>InstPrinter::printInstruction()``, among |
| 125 |
other things. |
| 126 |
|
| 127 |
**Usage**: Included directly into ``InstPrinter/<Target>InstPrinter.cpp``. |
| 128 |
|
| 129 |
AsmMatcher |
| 130 |
---------- |
| 131 |
|
| 132 |
**Purpose**: Emits a target specifier matcher for |
| 133 |
converting parsed assembly operands in the ``MCInst`` structures. It also |
| 134 |
emits a matcher for custom operand parsing. Extensive documentation is |
| 135 |
written on the ``AsmMatcherEmitter.cpp`` file. |
| 136 |
|
| 137 |
**Output**: Assembler parsers' matcher functions, declarations, etc. |
| 138 |
|
| 139 |
**Usage**: Used in back-ends' ``AsmParser/<Target>AsmParser.cpp`` for |
| 140 |
building the AsmParser class. |
| 141 |
|
| 142 |
Disassembler |
| 143 |
------------ |
| 144 |
|
| 145 |
**Purpose**: Contains disassembler table emitters for various |
| 146 |
architectures. Extensive documentation is written on the |
| 147 |
``DisassemblerEmitter.cpp`` file. |
| 148 |
|
| 149 |
**Output**: Decoding tables, static decoding functions, etc. |
| 150 |
|
| 151 |
**Usage**: Directly included in ``Disassembler/<Target>Disassembler.cpp`` |
| 152 |
to cater for all default decodings, after all hand-made ones. |
| 153 |
|
| 154 |
PseudoLowering |
| 155 |
-------------- |
| 156 |
|
| 157 |
**Purpose**: Generate pseudo instruction lowering. |
| 158 |
|
| 159 |
**Output**: Implements ``<Target>AsmPrinter::emitPseudoExpansionLowering()``. |
| 160 |
|
| 161 |
**Usage**: Included directly into ``<Target>AsmPrinter.cpp``. |
| 162 |
|
| 163 |
CallingConv |
| 164 |
----------- |
| 165 |
|
| 166 |
**Purpose**: Responsible for emitting descriptions of the calling |
| 167 |
conventions supported by this target. |
| 168 |
|
| 169 |
**Output**: Implement static functions to deal with calling conventions |
| 170 |
chained by matching styles, returning ``false`` on no match. |
| 171 |
|
| 172 |
**Usage**: Used in ISelLowering and FastIsel as function pointers to |
| 173 |
implementation returned by a CC selection function. |
| 174 |
|
| 175 |
DAGISel |
| 176 |
------- |
| 177 |
|
| 178 |
**Purpose**: Generate a DAG instruction selector. |
| 179 |
|
| 180 |
**Output**: Creates huge functions for automating DAG selection. |
| 181 |
|
| 182 |
**Usage**: Included in ``<Target>ISelDAGToDAG.cpp`` inside the target's |
| 183 |
implementation of ``SelectionDAGISel``. |
| 184 |
|
| 185 |
DFAPacketizer |
| 186 |
------------- |
| 187 |
|
| 188 |
**Purpose**: This class parses the Schedule.td file and produces an API that |
| 189 |
can be used to reason about whether an instruction can be added to a packet |
| 190 |
on a VLIW architecture. The class internally generates a deterministic finite |
| 191 |
automaton (DFA) that models all possible mappings of machine instructions |
| 192 |
to functional units as instructions are added to a packet. |
| 193 |
|
| 194 |
**Output**: Scheduling tables for GPU back-ends (Hexagon, AMD). |
| 195 |
|
| 196 |
**Usage**: Included directly on ``<Target>InstrInfo.cpp``. |
| 197 |
|
| 198 |
FastISel |
| 199 |
-------- |
| 200 |
|
| 201 |
**Purpose**: This tablegen backend emits code for use by the "fast" |
| 202 |
instruction selection algorithm. See the comments at the top of |
| 203 |
``lib/CodeGen/SelectionDAG/FastISel.cpp`` for background. This file |
| 204 |
scans through the target's tablegen instruction-info files |
| 205 |
and extracts instructions with obvious-looking patterns, and it emits |
| 206 |
code to look up these instructions by type and operator. |
| 207 |
|
| 208 |
**Output**: Generates ``Predicate`` and ``FastEmit`` methods. |
| 209 |
|
| 210 |
**Usage**: Implements private methods of the targets' implementation |
| 211 |
of ``FastISel`` class. |
| 212 |
|
| 213 |
Subtarget |
| 214 |
--------- |
| 215 |
|
| 216 |
**Purpose**: Generate subtarget enumerations. |
| 217 |
|
| 218 |
**Output**: Enums, globals, local tables for sub-target information. |
| 219 |
|
| 220 |
**Usage**: Populates ``<Target>Subtarget`` and |
| 221 |
``MCTargetDesc/<Target>MCTargetDesc`` files (both headers and source). |
| 222 |
|
| 223 |
Intrinsic |
| 224 |
--------- |
| 225 |
|
| 226 |
**Purpose**: Generate (target) intrinsic information. |
| 227 |
|
| 228 |
OptParserDefs |
| 229 |
------------- |
| 230 |
|
| 231 |
**Purpose**: Print enum values for a class. |
| 232 |
|
| 233 |
SearchableTables |
| 234 |
---------------- |
| 235 |
|
| 236 |
**Purpose**: Generate custom searchable tables. |
| 237 |
|
| 238 |
**Output**: Enums, global tables, and lookup helper functions. |
| 239 |
|
| 240 |
**Usage**: This backend allows generating free-form, target-specific tables |
| 241 |
from TableGen records. The ARM and AArch64 targets use this backend to generate |
| 242 |
tables of system registers; the AMDGPU target uses it to generate meta-data |
| 243 |
about complex image and memory buffer instructions. |
| 244 |
|
| 245 |
See `SearchableTables Reference`_ for a detailed description. |
| 246 |
|
| 247 |
CTags |
| 248 |
----- |
| 249 |
|
| 250 |
**Purpose**: This tablegen backend emits an index of definitions in ctags(1) |
| 251 |
format. A helper script, utils/TableGen/tdtags, provides an easier-to-use |
| 252 |
interface; run 'tdtags -H' for documentation. |
| 253 |
|
| 254 |
X86EVEX2VEX |
| 255 |
----------- |
| 256 |
|
| 257 |
**Purpose**: This X86 specific tablegen backend emits tables that map EVEX |
| 258 |
encoded instructions to their VEX encoded identical instruction. |
| 259 |
|
| 260 |
Clang BackEnds |
| 261 |
============== |
| 262 |
|
| 263 |
ClangAttrClasses |
| 264 |
---------------- |
| 265 |
|
| 266 |
**Purpose**: Creates Attrs.inc, which contains semantic attribute class |
| 267 |
declarations for any attribute in ``Attr.td`` that has not set ``ASTNode = 0``. |
| 268 |
This file is included as part of ``Attr.h``. |
| 269 |
|
| 270 |
ClangAttrParserStringSwitches |
| 271 |
----------------------------- |
| 272 |
|
| 273 |
**Purpose**: Creates ``AttrParserStringSwitches.inc``, which contains |
| 274 |
``StringSwitch::Case`` statements for parser-related string switches. Each switch |
| 275 |
is given its own macro (such as ``CLANG_ATTR_ARG_CONTEXT_LIST``, or |
| 276 |
``CLANG_ATTR_IDENTIFIER_ARG_LIST``), which is expected to be defined before |
| 277 |
including ``AttrParserStringSwitches.inc``, and undefined after. |
| 278 |
|
| 279 |
ClangAttrImpl |
| 280 |
------------- |
| 281 |
|
| 282 |
**Purpose**: Creates ``AttrImpl.inc``, which contains semantic attribute class |
| 283 |
definitions for any attribute in ``Attr.td`` that has not set ``ASTNode = 0``. |
| 284 |
This file is included as part of ``AttrImpl.cpp``. |
| 285 |
|
| 286 |
ClangAttrList |
| 287 |
------------- |
| 288 |
|
| 289 |
**Purpose**: Creates ``AttrList.inc``, which is used when a list of semantic |
| 290 |
attribute identifiers is required. For instance, ``AttrKinds.h`` includes this |
| 291 |
file to generate the list of ``attr::Kind`` enumeration values. This list is |
| 292 |
separated out into multiple categories: attributes, inheritable attributes, and |
| 293 |
inheritable parameter attributes. This categorization happens automatically |
| 294 |
based on information in ``Attr.td`` and is used to implement the ``classof`` |
| 295 |
functionality required for ``dyn_cast`` and similar APIs. |
| 296 |
|
| 297 |
ClangAttrPCHRead |
| 298 |
---------------- |
| 299 |
|
| 300 |
**Purpose**: Creates ``AttrPCHRead.inc``, which is used to deserialize attributes |
| 301 |
in the ``ASTReader::ReadAttributes`` function. |
| 302 |
|
| 303 |
ClangAttrPCHWrite |
| 304 |
----------------- |
| 305 |
|
| 306 |
**Purpose**: Creates ``AttrPCHWrite.inc``, which is used to serialize attributes in |
| 307 |
the ``ASTWriter::WriteAttributes`` function. |
| 308 |
|
| 309 |
ClangAttrSpellings |
| 310 |
--------------------- |
| 311 |
|
| 312 |
**Purpose**: Creates ``AttrSpellings.inc``, which is used to implement the |
| 313 |
``__has_attribute`` feature test macro. |
| 314 |
|
| 315 |
ClangAttrSpellingListIndex |
| 316 |
-------------------------- |
| 317 |
|
| 318 |
**Purpose**: Creates ``AttrSpellingListIndex.inc``, which is used to map parsed |
| 319 |
attribute spellings (including which syntax or scope was used) to an attribute |
| 320 |
spelling list index. These spelling list index values are internal |
| 321 |
implementation details exposed via |
| 322 |
``AttributeList::getAttributeSpellingListIndex``. |
| 323 |
|
| 324 |
ClangAttrVisitor |
| 325 |
------------------- |
| 326 |
|
| 327 |
**Purpose**: Creates ``AttrVisitor.inc``, which is used when implementing |
| 328 |
recursive AST visitors. |
| 329 |
|
| 330 |
ClangAttrTemplateInstantiate |
| 331 |
---------------------------- |
| 332 |
|
| 333 |
**Purpose**: Creates ``AttrTemplateInstantiate.inc``, which implements the |
| 334 |
``instantiateTemplateAttribute`` function, used when instantiating a template |
| 335 |
that requires an attribute to be cloned. |
| 336 |
|
| 337 |
ClangAttrParsedAttrList |
| 338 |
----------------------- |
| 339 |
|
| 340 |
**Purpose**: Creates ``AttrParsedAttrList.inc``, which is used to generate the |
| 341 |
``AttributeList::Kind`` parsed attribute enumeration. |
| 342 |
|
| 343 |
ClangAttrParsedAttrImpl |
| 344 |
----------------------- |
| 345 |
|
| 346 |
**Purpose**: Creates ``AttrParsedAttrImpl.inc``, which is used by |
| 347 |
``AttributeList.cpp`` to implement several functions on the ``AttributeList`` |
| 348 |
class. This functionality is implemented via the ``AttrInfoMap ParsedAttrInfo`` |
| 349 |
array, which contains one element per parsed attribute object. |
| 350 |
|
| 351 |
ClangAttrParsedAttrKinds |
| 352 |
------------------------ |
| 353 |
|
| 354 |
**Purpose**: Creates ``AttrParsedAttrKinds.inc``, which is used to implement the |
| 355 |
``AttributeList::getKind`` function, mapping a string (and syntax) to a parsed |
| 356 |
attribute ``AttributeList::Kind`` enumeration. |
| 357 |
|
| 358 |
ClangAttrIsTypeDependent |
| 359 |
------------------------ |
| 360 |
|
| 361 |
**Purpose**: Creates ``AttrIsTypeDependent.inc``, which is used to implement the |
| 362 |
``Sema::CheckAttributesOnDeducedType`` function, mapping an attribute kind to a |
| 363 |
Sema function if it exists. |
| 364 |
|
| 365 |
ClangAttrDump |
| 366 |
------------- |
| 367 |
|
| 368 |
**Purpose**: Creates ``AttrDump.inc``, which dumps information about an attribute. |
| 369 |
It is used to implement ``ASTDumper::dumpAttr``. |
| 370 |
|
| 371 |
ClangDiagsDefs |
| 372 |
-------------- |
| 373 |
|
| 374 |
Generate Clang diagnostics definitions. |
| 375 |
|
| 376 |
ClangDiagGroups |
| 377 |
--------------- |
| 378 |
|
| 379 |
Generate Clang diagnostic groups. |
| 380 |
|
| 381 |
ClangDiagsIndexName |
| 382 |
------------------- |
| 383 |
|
| 384 |
Generate Clang diagnostic name index. |
| 385 |
|
| 386 |
ClangCommentNodes |
| 387 |
----------------- |
| 388 |
|
| 389 |
Generate Clang AST comment nodes. |
| 390 |
|
| 391 |
ClangDeclNodes |
| 392 |
-------------- |
| 393 |
|
| 394 |
Generate Clang AST declaration nodes. |
| 395 |
|
| 396 |
ClangStmtNodes |
| 397 |
-------------- |
| 398 |
|
| 399 |
Generate Clang AST statement nodes. |
| 400 |
|
| 401 |
ClangSACheckers |
| 402 |
--------------- |
| 403 |
|
| 404 |
Generate Clang Static Analyzer checkers. |
| 405 |
|
| 406 |
ClangCommentHTMLTags |
| 407 |
-------------------- |
| 408 |
|
| 409 |
Generate efficient matchers for HTML tag names that are used in documentation comments. |
| 410 |
|
| 411 |
ClangCommentHTMLTagsProperties |
| 412 |
------------------------------ |
| 413 |
|
| 414 |
Generate efficient matchers for HTML tag properties. |
| 415 |
|
| 416 |
ClangCommentHTMLNamedCharacterReferences |
| 417 |
---------------------------------------- |
| 418 |
|
| 419 |
Generate function to translate named character references to UTF-8 sequences. |
| 420 |
|
| 421 |
ClangCommentCommandInfo |
| 422 |
----------------------- |
| 423 |
|
| 424 |
Generate command properties for commands that are used in documentation comments. |
| 425 |
|
| 426 |
ClangCommentCommandList |
| 427 |
----------------------- |
| 428 |
|
| 429 |
Generate list of commands that are used in documentation comments. |
| 430 |
|
| 431 |
ArmNeon |
| 432 |
------- |
| 433 |
|
| 434 |
Generate ``arm_neon.h`` for clang. |
| 435 |
|
| 436 |
ArmNeonSema |
| 437 |
----------- |
| 438 |
|
| 439 |
Generate ARM NEON sema support for clang. |
| 440 |
|
| 441 |
ArmNeonTest |
| 442 |
----------- |
| 443 |
|
| 444 |
Generate ARM NEON tests for clang. |
| 445 |
|
| 446 |
AttrDocs |
| 447 |
-------- |
| 448 |
|
| 449 |
**Purpose**: Creates ``AttributeReference.rst`` from ``AttrDocs.td``, and is |
| 450 |
used for documenting user-facing attributes. |
| 451 |
|
| 452 |
General BackEnds |
| 453 |
================ |
| 454 |
|
| 455 |
Print Records |
| 456 |
------------- |
| 457 |
|
| 458 |
The TableGen command option ``--print-records`` invokes a simple backend |
| 459 |
that prints all the classes and records defined in the source files. This is |
| 460 |
the default backend option. See the :doc:`TableGen Backend Developer's Guide |
| 461 |
<./BackGuide>` for more information. |
| 462 |
|
| 463 |
Print Detailed Records |
| 464 |
---------------------- |
| 465 |
|
| 466 |
The TableGen command option ``--print-detailed-records`` invokes a backend |
| 467 |
that prints all the global variables, classes, and records defined in the |
| 468 |
source files, with more detail than the default record printer. See the |
| 469 |
:doc:`TableGen Backend Developer's Guide <./BackGuide>` for more |
| 470 |
information. |
| 471 |
|
| 472 |
JSON Reference |
| 473 |
-------------- |
| 474 |
|
| 475 |
**Purpose**: Output all the values in every ``def``, as a JSON data |
| 476 |
structure that can be easily parsed by a variety of languages. Useful |
| 477 |
for writing custom backends without having to modify TableGen itself, |
| 478 |
or for performing auxiliary analysis on the same TableGen data passed |
| 479 |
to a built-in backend. |
| 480 |
|
| 481 |
**Output**: |
| 482 |
|
| 483 |
The root of the output file is a JSON object (i.e., dictionary), |
| 484 |
containing the following fixed keys: |
| 485 |
|
| 486 |
* ``!tablegen_json_version``: a numeric version field that will |
| 487 |
increase if an incompatible change is ever made to the structure of |
| 488 |
this data. The format described here corresponds to version 1. |
| 489 |
|
| 490 |
* ``!instanceof``: a dictionary whose keys are the class names defined |
| 491 |
in the TableGen input. For each key, the corresponding value is an |
| 492 |
array of strings giving the names of ``def`` records that derive |
| 493 |
from that class. So ``root["!instanceof"]["Instruction"]``, for |
| 494 |
example, would list the names of all the records deriving from the |
| 495 |
class ``Instruction``. |
| 496 |
|
| 497 |
For each ``def`` record, the root object also has a key for the record |
| 498 |
name. The corresponding value is a subsidiary object containing the |
| 499 |
following fixed keys: |
| 500 |
|
| 501 |
* ``!superclasses``: an array of strings giving the names of all the |
| 502 |
classes that this record derives from. |
| 503 |
|
| 504 |
* ``!fields``: an array of strings giving the names of all the variables |
| 505 |
in this record that were defined with the ``field`` keyword. |
| 506 |
|
| 507 |
* ``!name``: a string giving the name of the record. This is always |
| 508 |
identical to the key in the JSON root object corresponding to this |
| 509 |
record's dictionary. (If the record is anonymous, the name is |
| 510 |
arbitrary.) |
| 511 |
|
| 512 |
* ``!anonymous``: a boolean indicating whether the record's name was |
| 513 |
specified by the TableGen input (if it is ``false``), or invented by |
| 514 |
TableGen itself (if ``true``). |
| 515 |
|
| 516 |
* ``!locs``: an array of strings giving the source locations associated with |
| 517 |
this record. For records instantiated from a ``multiclass``, this gives the |
| 518 |
location of each ``def`` or ``defm``, starting with the inner-most |
| 519 |
``multiclass``, and ending with the top-level ``defm``. Each string contains |
| 520 |
the file name and line number, separated by a colon. |
| 521 |
|
| 522 |
For each variable defined in a record, the ``def`` object for that |
| 523 |
record also has a key for the variable name. The corresponding value |
| 524 |
is a translation into JSON of the variable's value, using the |
| 525 |
conventions described below. |
| 526 |
|
| 527 |
Some TableGen data types are translated directly into the |
| 528 |
corresponding JSON type: |
| 529 |
|
| 530 |
* A completely undefined value (e.g., for a variable declared without |
| 531 |
initializer in some superclass of this record, and never initialized |
| 532 |
by the record itself or any other superclass) is emitted as the JSON |
| 533 |
``null`` value. |
| 534 |
|
| 535 |
* ``int`` and ``bit`` values are emitted as numbers. Note that |
| 536 |
TableGen ``int`` values are capable of holding integers too large to |
| 537 |
be exactly representable in IEEE double precision. The integer |
| 538 |
literal in the JSON output will show the full exact integer value. |
| 539 |
So if you need to retrieve large integers with full precision, you |
| 540 |
should use a JSON reader capable of translating such literals back |
| 541 |
into 64-bit integers without losing precision, such as Python's |
| 542 |
standard ``json`` module. |
| 543 |
|
| 544 |
* ``string`` and ``code`` values are emitted as JSON strings. |
| 545 |
|
| 546 |
* ``list<T>`` values, for any element type ``T``, are emitted as JSON |
| 547 |
arrays. Each element of the array is represented in turn using these |
| 548 |
same conventions. |
| 549 |
|
| 550 |
* ``bits`` values are also emitted as arrays. A ``bits`` array is |
| 551 |
ordered from least-significant bit to most-significant. So the |
| 552 |
element with index ``i`` corresponds to the bit described as |
| 553 |
``x{i}`` in TableGen source. However, note that this means that |
| 554 |
scripting languages are likely to *display* the array in the |
| 555 |
opposite order from the way it appears in the TableGen source or in |
| 556 |
the diagnostic ``-print-records`` output. |
| 557 |
|
| 558 |
All other TableGen value types are emitted as a JSON object, |
| 559 |
containing two standard fields: ``kind`` is a discriminator describing |
| 560 |
which kind of value the object represents, and ``printable`` is a |
| 561 |
string giving the same representation of the value that would appear |
| 562 |
in ``-print-records``. |
| 563 |
|
| 564 |
* A reference to a ``def`` object has ``kind=="def"``, and has an |
| 565 |
extra field ``def`` giving the name of the object referred to. |
| 566 |
|
| 567 |
* A reference to another variable in the same record has |
| 568 |
``kind=="var"``, and has an extra field ``var`` giving the name of |
| 569 |
the variable referred to. |
| 570 |
|
| 571 |
* A reference to a specific bit of a ``bits``-typed variable in the |
| 572 |
same record has ``kind=="varbit"``, and has two extra fields: |
| 573 |
``var`` gives the name of the variable referred to, and ``index`` |
| 574 |
gives the index of the bit. |
| 575 |
|
| 576 |
* A value of type ``dag`` has ``kind=="dag"``, and has two extra |
| 577 |
fields. ``operator`` gives the initial value after the opening |
| 578 |
parenthesis of the dag initializer; ``args`` is an array giving the |
| 579 |
following arguments. The elements of ``args`` are arrays of length |
| 580 |
2, giving the value of each argument followed by its colon-suffixed |
| 581 |
name (if any). For example, in the JSON representation of the dag |
| 582 |
value ``(Op 22, "hello":$foo)`` (assuming that ``Op`` is the name of |
| 583 |
a record defined elsewhere with a ``def`` statement): |
| 584 |
|
| 585 |
* ``operator`` will be an object in which ``kind=="def"`` and |
| 586 |
``def=="Op"`` |
| 587 |
|
| 588 |
* ``args`` will be the array ``[[22, null], ["hello", "foo"]]``. |
| 589 |
|
| 590 |
* If any other kind of value or complicated expression appears in the |
| 591 |
output, it will have ``kind=="complex"``, and no additional fields. |
| 592 |
These values are not expected to be needed by backends. The standard |
| 593 |
``printable`` field can be used to extract a representation of them |
| 594 |
in TableGen source syntax if necessary. |
| 595 |
|
| 596 |
SearchableTables Reference |
| 597 |
-------------------------- |
| 598 |
|
| 599 |
A TableGen include file, ``SearchableTable.td``, provides classes for |
| 600 |
generating C++ searchable tables. These tables are described in the |
| 601 |
following sections. To generate the C++ code, run ``llvm-tblgen`` with the |
| 602 |
``--gen-searchable-tables`` option, which invokes the backend that generates |
| 603 |
the tables from the records you provide. |
| 604 |
|
| 605 |
Each of the data structures generated for searchable tables is guarded by an |
| 606 |
``#ifdef``. This allows you to include the generated ``.inc`` file and select only |
| 607 |
certain data structures for inclusion. The examples below show the macro |
| 608 |
names used in these guards. |
| 609 |
|
| 610 |
Generic Enumerated Types |
| 611 |
~~~~~~~~~~~~~~~~~~~~~~~~ |
| 612 |
|
| 613 |
The ``GenericEnum`` class makes it easy to define a C++ enumerated type and |
| 614 |
the enumerated *elements* of that type. To define the type, define a record |
| 615 |
whose parent class is ``GenericEnum`` and whose name is the desired enum |
| 616 |
type. This class provides three fields, which you can set in the record |
| 617 |
using the ``let`` statement. |
| 618 |
|
| 619 |
* ``string FilterClass``. The enum type will have one element for each record |
| 620 |
that derives from this class. These records are collected to assemble the |
| 621 |
complete set of elements. |
| 622 |
|
| 623 |
* ``string NameField``. The name of a field *in the collected records* that specifies |
| 624 |
the name of the element. If a record has no such field, the record's |
| 625 |
name will be used. |
| 626 |
|
| 627 |
* ``string ValueField``. The name of a field *in the collected records* that |
| 628 |
specifies the numerical value of the element. If a record has no such |
| 629 |
field, it will be assigned an integer value. Values are assigned in |
| 630 |
alphabetical order starting with 0. |
| 631 |
|
| 632 |
Here is an example where the values of the elements are specified |
| 633 |
explicitly, as a template argument to the ``BEntry`` class. The resulting |
| 634 |
C++ code is shown. |
| 635 |
|
| 636 |
.. code-block:: text |
| 637 |
|
| 638 |
def BValues : GenericEnum { |
| 639 |
let FilterClass = "BEntry"; |
| 640 |
let NameField = "Name"; |
| 641 |
let ValueField = "Encoding"; |
| 642 |
} |
| 643 |
|
| 644 |
class BEntry<bits<16> enc> { |
| 645 |
string Name = NAME; |
| 646 |
bits<16> Encoding = enc; |
| 647 |
} |
| 648 |
|
| 649 |
def BFoo : BEntry<0xac>; |
| 650 |
def BBar : BEntry<0x14>; |
| 651 |
def BZoo : BEntry<0x80>; |
| 652 |
def BSnork : BEntry<0x4c>; |
| 653 |
|
| 654 |
.. code-block:: text |
| 655 |
|
| 656 |
#ifdef GET_BValues_DECL |
| 657 |
enum BValues { |
| 658 |
BBar = 20, |
| 659 |
BFoo = 172, |
| 660 |
BSnork = 76, |
| 661 |
BZoo = 128, |
| 662 |
}; |
| 663 |
#endif |
| 664 |
|
| 665 |
In the following example, the values of the elements are assigned |
| 666 |
automatically. Note that values are assigned from 0, in alphabetical order |
| 667 |
by element name. |
| 668 |
|
| 669 |
.. code-block:: text |
| 670 |
|
| 671 |
def CEnum : GenericEnum { |
| 672 |
let FilterClass = "CEnum"; |
| 673 |
} |
| 674 |
|
| 675 |
class CEnum; |
| 676 |
|
| 677 |
def CFoo : CEnum; |
| 678 |
def CBar : CEnum; |
| 679 |
def CBaz : CEnum; |
| 680 |
|
| 681 |
.. code-block:: text |
| 682 |
|
| 683 |
#ifdef GET_CEnum_DECL |
| 684 |
enum CEnum { |
| 685 |
CBar = 0, |
| 686 |
CBaz = 1, |
| 687 |
CFoo = 2, |
| 688 |
}; |
| 689 |
#endif |
| 690 |
|
| 691 |
|
| 692 |
Generic Tables |
| 693 |
~~~~~~~~~~~~~~ |
| 694 |
|
| 695 |
The ``GenericTable`` class is used to define a searchable generic table. |
| 696 |
TableGen produces C++ code to define the table entries and also produces |
| 697 |
the declaration and definition of a function to search the table based on a |
| 698 |
primary key. To define the table, define a record whose parent class is |
| 699 |
``GenericTable`` and whose name is the name of the global table of entries. |
| 700 |
This class provides six fields. |
| 701 |
|
| 702 |
* ``string FilterClass``. The table will have one entry for each record |
| 703 |
that derives from this class. |
| 704 |
|
| 705 |
* ``string FilterClassField``. This is an optional field of ``FilterClass`` |
| 706 |
which should be `bit` type. If specified, only those records with this field |
| 707 |
being true will have corresponding entries in the table. This field won't be |
| 708 |
included in generated C++ fields if it isn't included in ``Fields`` list. |
| 709 |
|
| 710 |
* ``string CppTypeName``. The name of the C++ struct/class type of the |
| 711 |
table that holds the entries. If unspecified, the ``FilterClass`` name is |
| 712 |
used. |
| 713 |
|
| 714 |
* ``list<string> Fields``. A list of the names of the fields *in the |
| 715 |
collected records* that contain the data for the table entries. The order of |
| 716 |
this list determines the order of the values in the C++ initializers. See |
| 717 |
below for information about the types of these fields. |
| 718 |
|
| 719 |
* ``list<string> PrimaryKey``. The list of fields that make up the |
| 720 |
primary key. |
| 721 |
|
| 722 |
* ``string PrimaryKeyName``. The name of the generated C++ function |
| 723 |
that performs a lookup on the primary key. |
| 724 |
|
| 725 |
* ``bit PrimaryKeyEarlyOut``. See the third example below. |
| 726 |
|
| 727 |
* ``bit PrimaryKeyReturnRange``. when set to 1, modifies the lookup function’s |
| 728 |
definition to return a range of results rather than a single pointer to the |
| 729 |
object. This feature proves useful when multiple objects meet the criteria |
| 730 |
specified by the lookup function. Currently, it is supported only for primary |
| 731 |
lookup functions. Refer to the second example below for further details. |
| 732 |
|
| 733 |
TableGen attempts to deduce the type of each of the table fields so that it |
| 734 |
can format the C++ initializers in the emitted table. It can deduce ``bit``, |
| 735 |
``bits<n>``, ``string``, ``Intrinsic``, and ``Instruction``. These can be |
| 736 |
used in the primary key. Any other field types must be specified |
| 737 |
explicitly; this is done as shown in the second example below. Such fields |
| 738 |
cannot be used in the primary key. |
| 739 |
|
| 740 |
One special case of the field type has to do with code. Arbitrary code is |
| 741 |
represented by a string, but has to be emitted as a C++ initializer without |
| 742 |
quotes. If the code field was defined using a code literal (``[{...}]``), |
| 743 |
then TableGen will know to emit it without quotes. However, if it was |
| 744 |
defined using a string literal or complex string expression, then TableGen |
| 745 |
will not know. In this case, you can force TableGen to treat the field as |
| 746 |
code by including the following line in the ``GenericTable`` record, where |
| 747 |
*xxx* is the code field name. |
| 748 |
|
| 749 |
.. code-block:: text |
| 750 |
|
| 751 |
string TypeOf_xxx = "code"; |
| 752 |
|
| 753 |
Here is an example where TableGen can deduce the field types. Note that the |
| 754 |
table entry records are anonymous; the names of entry records are |
| 755 |
irrelevant. |
| 756 |
|
| 757 |
.. code-block:: text |
| 758 |
|
| 759 |
def ATable : GenericTable { |
| 760 |
let FilterClass = "AEntry"; |
| 761 |
let FilterClassField = "IsNeeded"; |
| 762 |
let Fields = ["Str", "Val1", "Val2"]; |
| 763 |
let PrimaryKey = ["Val1", "Val2"]; |
| 764 |
let PrimaryKeyName = "lookupATableByValues"; |
| 765 |
} |
| 766 |
|
| 767 |
class AEntry<string str, int val1, int val2, bit isNeeded> { |
| 768 |
string Str = str; |
| 769 |
bits<8> Val1 = val1; |
| 770 |
bits<10> Val2 = val2; |
| 771 |
bit IsNeeded = isNeeded; |
| 772 |
} |
| 773 |
|
| 774 |
def : AEntry<"Bob", 5, 3, 1>; |
| 775 |
def : AEntry<"Carol", 2, 6, 1>; |
| 776 |
def : AEntry<"Ted", 4, 4, 1>; |
| 777 |
def : AEntry<"Alice", 4, 5, 1>; |
| 778 |
def : AEntry<"Costa", 2, 1, 1>; |
| 779 |
def : AEntry<"Dale", 2, 1, 0>; |
| 780 |
|
| 781 |
Here is the generated C++ code. The declaration of ``lookupATableByValues`` |
| 782 |
is guarded by ``GET_ATable_DECL``, while the definitions are guarded by |
| 783 |
``GET_ATable_IMPL``. |
| 784 |
|
| 785 |
.. code-block:: text |
| 786 |
|
| 787 |
#ifdef GET_ATable_DECL |
| 788 |
const AEntry *lookupATableByValues(uint8_t Val1, uint16_t Val2); |
| 789 |
#endif |
| 790 |
|
| 791 |
#ifdef GET_ATable_IMPL |
| 792 |
constexpr AEntry ATable[] = { |
| 793 |
{ "Costa", 0x2, 0x1 }, // 0 |
| 794 |
{ "Carol", 0x2, 0x6 }, // 1 |
| 795 |
{ "Ted", 0x4, 0x4 }, // 2 |
| 796 |
{ "Alice", 0x4, 0x5 }, // 3 |
| 797 |
{ "Bob", 0x5, 0x3 }, // 4 |
| 798 |
/* { "Dale", 0x2, 0x1 }, // 5 */ // We don't generate this line as `IsNeeded` is 0. |
| 799 |
}; |
| 800 |
|
| 801 |
const AEntry *lookupATableByValues(uint8_t Val1, uint16_t Val2) { |
| 802 |
struct KeyType { |
| 803 |
uint8_t Val1; |
| 804 |
uint16_t Val2; |
| 805 |
}; |
| 806 |
KeyType Key = { Val1, Val2 }; |
| 807 |
auto Table = ArrayRef(ATable); |
| 808 |
auto Idx = std::lower_bound(Table.begin(), Table.end(), Key, |
| 809 |
[](const AEntry &LHS, const KeyType &RHS) { |
| 810 |
if (LHS.Val1 < RHS.Val1) |
| 811 |
return true; |
| 812 |
if (LHS.Val1 > RHS.Val1) |
| 813 |
return false; |
| 814 |
if (LHS.Val2 < RHS.Val2) |
| 815 |
return true; |
| 816 |
if (LHS.Val2 > RHS.Val2) |
| 817 |
return false; |
| 818 |
return false; |
| 819 |
}); |
| 820 |
|
| 821 |
if (Idx == Table.end() || |
| 822 |
Key.Val1 != Idx->Val1 || |
| 823 |
Key.Val2 != Idx->Val2) |
| 824 |
return nullptr; |
| 825 |
return &*Idx; |
| 826 |
} |
| 827 |
#endif |
| 828 |
|
| 829 |
The table entries in ``ATable`` are sorted in order by ``Val1``, and within |
| 830 |
each of those values, by ``Val2``. This allows a binary search of the table, |
| 831 |
which is performed in the lookup function by ``std::lower_bound``. The |
| 832 |
lookup function returns a reference to the found table entry, or the null |
| 833 |
pointer if no entry is found. If the table has a single primary key field |
| 834 |
which is integral and densely numbered, a direct lookup is generated rather |
| 835 |
than a binary search. |
| 836 |
|
| 837 |
This example includes a field whose type TableGen cannot deduce. The ``Kind`` |
| 838 |
field uses the enumerated type ``CEnum`` defined above. To inform TableGen |
| 839 |
of the type, the record derived from ``GenericTable`` must include a string field |
| 840 |
named ``TypeOf_``\ *field*, where *field* is the name of the field whose type |
| 841 |
is required. |
| 842 |
|
| 843 |
.. code-block:: text |
| 844 |
|
| 845 |
def CTable : GenericTable { |
| 846 |
let FilterClass = "CEntry"; |
| 847 |
let Fields = ["Name", "Kind", "Encoding"]; |
| 848 |
string TypeOf_Kind = "CEnum"; |
| 849 |
let PrimaryKey = ["Encoding"]; |
| 850 |
let PrimaryKeyName = "lookupCEntryByEncoding"; |
| 851 |
} |
| 852 |
|
| 853 |
class CEntry<string name, CEnum kind, int enc> { |
| 854 |
string Name = name; |
| 855 |
CEnum Kind = kind; |
| 856 |
bits<16> Encoding = enc; |
| 857 |
} |
| 858 |
|
| 859 |
def : CEntry<"Apple", CFoo, 10>; |
| 860 |
def : CEntry<"Pear", CBaz, 15>; |
| 861 |
def : CEntry<"Apple", CBar, 13>; |
| 862 |
|
| 863 |
Here is the generated C++ code. |
| 864 |
|
| 865 |
.. code-block:: text |
| 866 |
|
| 867 |
#ifdef GET_CTable_DECL |
| 868 |
const CEntry *lookupCEntryByEncoding(uint16_t Encoding); |
| 869 |
#endif |
| 870 |
|
| 871 |
#ifdef GET_CTable_IMPL |
| 872 |
constexpr CEntry CTable[] = { |
| 873 |
{ "Apple", CFoo, 0xA }, // 0 |
| 874 |
{ "Apple", CBar, 0xD }, // 1 |
| 875 |
{ "Pear", CBaz, 0xF }, // 2 |
| 876 |
}; |
| 877 |
|
| 878 |
const CEntry *lookupCEntryByEncoding(uint16_t Encoding) { |
| 879 |
struct KeyType { |
| 880 |
uint16_t Encoding; |
| 881 |
}; |
| 882 |
KeyType Key = { Encoding }; |
| 883 |
auto Table = ArrayRef(CTable); |
| 884 |
auto Idx = std::lower_bound(Table.begin(), Table.end(), Key, |
| 885 |
[](const CEntry &LHS, const KeyType &RHS) { |
| 886 |
if (LHS.Encoding < RHS.Encoding) |
| 887 |
return true; |
| 888 |
if (LHS.Encoding > RHS.Encoding) |
| 889 |
return false; |
| 890 |
return false; |
| 891 |
}); |
| 892 |
|
| 893 |
if (Idx == Table.end() || |
| 894 |
Key.Encoding != Idx->Encoding) |
| 895 |
return nullptr; |
| 896 |
return &*Idx; |
| 897 |
} |
| 898 |
|
| 899 |
In the above example, lets add one more record with encoding same as that of |
| 900 |
record ``CEntry<"Pear", CBaz, 15>``. |
| 901 |
|
| 902 |
.. code-block:: text |
| 903 |
|
| 904 |
def CFoobar : CEnum; |
| 905 |
def : CEntry<"Banana", CFoobar, 15>; |
| 906 |
|
| 907 |
Below is the new generated ``CTable`` |
| 908 |
|
| 909 |
.. code-block:: text |
| 910 |
|
| 911 |
#ifdef GET_Table_IMPL |
| 912 |
constexpr CEntry Table[] = { |
| 913 |
{ "Apple", CFoo, 0xA }, // 0 |
| 914 |
{ "Apple", CBar, 0xD }, // 1 |
| 915 |
{ "Banana", CFoobar, 0xF }, // 2 |
| 916 |
{ "Pear", CBaz, 0xF }, // 3 |
| 917 |
}; |
| 918 |
|
| 919 |
Since ``Banana`` lexicographically appears first, therefore in the ``CEntry`` |
| 920 |
table, record with name ``Banana`` will come before the record with name |
| 921 |
``Pear``. Because of this, the ``lookupCEntryByEncoding`` function will always |
| 922 |
return a pointer to the record with name ``Banana`` even though in some cases |
| 923 |
the correct result can be the record with name ``Pear``. Such kind of scenario |
| 924 |
makes the existing lookup function insufficient because they always return a |
| 925 |
pointer to a single entry from the table, but instead it should return a range |
| 926 |
of results because multiple entries match the criteria sought by the lookup |
| 927 |
function. In this case, the definition of the lookup function needs to be |
| 928 |
modified to return a range of results which can be done by setting |
| 929 |
``PrimaryKeyReturnRange``. |
| 930 |
|
| 931 |
.. code-block:: text |
| 932 |
|
| 933 |
def CTable : GenericTable { |
| 934 |
let FilterClass = "CEntry"; |
| 935 |
let Fields = ["Name", "Kind", "Encoding"]; |
| 936 |
string TypeOf_Kind = "CEnum"; |
| 937 |
let PrimaryKey = ["Encoding"]; |
| 938 |
let PrimaryKeyName = "lookupCEntryByEncoding"; |
| 939 |
let PrimaryKeyReturnRange = true; |
| 940 |
} |
| 941 |
|
| 942 |
Here is the modified lookup function. |
| 943 |
|
| 944 |
.. code-block:: text |
| 945 |
|
| 946 |
llvm::iterator_range<const CEntry *> lookupCEntryByEncoding(uint16_t Encoding) { |
| 947 |
struct KeyType { |
| 948 |
uint16_t Encoding; |
| 949 |
}; |
| 950 |
KeyType Key = {Encoding}; |
| 951 |
struct Comp { |
| 952 |
bool operator()(const CEntry &LHS, const KeyType &RHS) const { |
| 953 |
if (LHS.Encoding < RHS.Encoding) |
| 954 |
return true; |
| 955 |
if (LHS.Encoding > RHS.Encoding) |
| 956 |
return false; |
| 957 |
return false; |
| 958 |
} |
| 959 |
bool operator()(const KeyType &LHS, const CEntry &RHS) const { |
| 960 |
if (LHS.Encoding < RHS.Encoding) |
| 961 |
return true; |
| 962 |
if (LHS.Encoding > RHS.Encoding) |
| 963 |
return false; |
| 964 |
return false; |
| 965 |
} |
| 966 |
}; |
| 967 |
auto Table = ArrayRef(Table); |
| 968 |
auto It = std::equal_range(Table.begin(), Table.end(), Key, Comp()); |
| 969 |
return llvm::make_range(It.first, It.second); |
| 970 |
} |
| 971 |
|
| 972 |
The new lookup function will return an iterator range with first pointer to the |
| 973 |
first result and the last pointer to the last matching result from the table. |
| 974 |
However, please note that the support for emitting a modified definition exists |
| 975 |
for ``PrimaryKeyName`` only. |
| 976 |
|
| 977 |
The ``PrimaryKeyEarlyOut`` field, when set to 1, modifies the lookup |
| 978 |
function so that it tests the first field of the primary key to determine |
| 979 |
whether it is within the range of the collected records' primary keys. If |
| 980 |
not, the function returns the null pointer without performing the binary |
| 981 |
search. This is useful for tables that provide data for only some of the |
| 982 |
elements of a larger enum-based space. The first field of the primary key |
| 983 |
must be an integral type; it cannot be a string. |
| 984 |
|
| 985 |
Adding ``let PrimaryKeyEarlyOut = 1`` to the ``ATable`` above: |
| 986 |
|
| 987 |
.. code-block:: text |
| 988 |
|
| 989 |
def ATable : GenericTable { |
| 990 |
let FilterClass = "AEntry"; |
| 991 |
let Fields = ["Str", "Val1", "Val2"]; |
| 992 |
let PrimaryKey = ["Val1", "Val2"]; |
| 993 |
let PrimaryKeyName = "lookupATableByValues"; |
| 994 |
let PrimaryKeyEarlyOut = 1; |
| 995 |
} |
| 996 |
|
| 997 |
causes the lookup function to change as follows: |
| 998 |
|
| 999 |
.. code-block:: text |
| 1000 |
|
| 1001 |
const AEntry *lookupATableByValues(uint8_t Val1, uint16_t Val2) { |
| 1002 |
if ((Val1 < 0x2) || |
| 1003 |
(Val1 > 0x5)) |
| 1004 |
return nullptr; |
| 1005 |
|
| 1006 |
struct KeyType { |
| 1007 |
... |
| 1008 |
|
| 1009 |
We can construct two GenericTables with the same ``FilterClass``, so that they |
| 1010 |
select from the same overall set of records, but assign them with different |
| 1011 |
``FilterClassField`` values so that they include different subsets of the |
| 1012 |
records of that class. |
| 1013 |
|
| 1014 |
For example, we can create two tables that contain only even or odd records. |
| 1015 |
Fields ``IsEven`` and ``IsOdd`` won't be included in generated C++ fields |
| 1016 |
because they aren't included in ``Fields`` list. |
| 1017 |
|
| 1018 |
.. code-block:: text |
| 1019 |
|
| 1020 |
class EEntry<bits<8> value> { |
| 1021 |
bits<8> Value = value; |
| 1022 |
bit IsEven = !eq(!and(value, 1), 0); |
| 1023 |
bit IsOdd = !not(IsEven); |
| 1024 |
} |
| 1025 |
|
| 1026 |
foreach i = {1-10} in { |
| 1027 |
def : EEntry<i>; |
| 1028 |
} |
| 1029 |
|
| 1030 |
def EEntryEvenTable : GenericTable { |
| 1031 |
let FilterClass = "EEntry"; |
| 1032 |
let FilterClassField = "IsEven"; |
| 1033 |
let Fields = ["Value"]; |
| 1034 |
let PrimaryKey = ["Value"]; |
| 1035 |
let PrimaryKeyName = "lookupEEntryEvenTableByValue"; |
| 1036 |
} |
| 1037 |
|
| 1038 |
def EEntryOddTable : GenericTable { |
| 1039 |
let FilterClass = "EEntry"; |
| 1040 |
let FilterClassField = "IsOdd"; |
| 1041 |
let Fields = ["Value"]; |
| 1042 |
let PrimaryKey = ["Value"]; |
| 1043 |
let PrimaryKeyName = "lookupEEntryOddTableByValue"; |
| 1044 |
} |
| 1045 |
|
| 1046 |
The generated tables are: |
| 1047 |
|
| 1048 |
.. code-block:: text |
| 1049 |
|
| 1050 |
constexpr EEntry EEntryEvenTable[] = { |
| 1051 |
{ 0x2 }, // 0 |
| 1052 |
{ 0x4 }, // 1 |
| 1053 |
{ 0x6 }, // 2 |
| 1054 |
{ 0x8 }, // 3 |
| 1055 |
{ 0xA }, // 4 |
| 1056 |
}; |
| 1057 |
|
| 1058 |
constexpr EEntry EEntryOddTable[] = { |
| 1059 |
{ 0x1 }, // 0 |
| 1060 |
{ 0x3 }, // 1 |
| 1061 |
{ 0x5 }, // 2 |
| 1062 |
{ 0x7 }, // 3 |
| 1063 |
{ 0x9 }, // 4 |
| 1064 |
}; |
| 1065 |
|
| 1066 |
Search Indexes |
| 1067 |
~~~~~~~~~~~~~~ |
| 1068 |
|
| 1069 |
The ``SearchIndex`` class is used to define additional lookup functions for |
| 1070 |
generic tables. To define an additional function, define a record whose parent |
| 1071 |
class is ``SearchIndex`` and whose name is the name of the desired lookup |
| 1072 |
function. This class provides three fields. |
| 1073 |
|
| 1074 |
* ``GenericTable Table``. The name of the table that is to receive another |
| 1075 |
lookup function. |
| 1076 |
|
| 1077 |
* ``list<string> Key``. The list of fields that make up the secondary key. |
| 1078 |
|
| 1079 |
* ``bit EarlyOut``. See the third example in `Generic Tables`_. |
| 1080 |
|
| 1081 |
Here is an example of a secondary key added to the ``CTable`` above. The |
| 1082 |
generated function looks up entries based on the ``Name`` and ``Kind`` fields. |
| 1083 |
|
| 1084 |
.. code-block:: text |
| 1085 |
|
| 1086 |
def lookupCEntry : SearchIndex { |
| 1087 |
let Table = CTable; |
| 1088 |
let Key = ["Name", "Kind"]; |
| 1089 |
} |
| 1090 |
|
| 1091 |
This use of ``SearchIndex`` generates the following additional C++ code. |
| 1092 |
|
| 1093 |
.. code-block:: text |
| 1094 |
|
| 1095 |
const CEntry *lookupCEntry(StringRef Name, unsigned Kind); |
| 1096 |
|
| 1097 |
... |
| 1098 |
|
| 1099 |
const CEntry *lookupCEntryByName(StringRef Name, unsigned Kind) { |
| 1100 |
struct IndexType { |
| 1101 |
const char * Name; |
| 1102 |
unsigned Kind; |
| 1103 |
unsigned _index; |
| 1104 |
}; |
| 1105 |
static const struct IndexType Index[] = { |
| 1106 |
{ "APPLE", CBar, 1 }, |
| 1107 |
{ "APPLE", CFoo, 0 }, |
| 1108 |
{ "PEAR", CBaz, 2 }, |
| 1109 |
}; |
| 1110 |
|
| 1111 |
struct KeyType { |
| 1112 |
std::string Name; |
| 1113 |
unsigned Kind; |
| 1114 |
}; |
| 1115 |
KeyType Key = { Name.upper(), Kind }; |
| 1116 |
auto Table = ArrayRef(Index); |
| 1117 |
auto Idx = std::lower_bound(Table.begin(), Table.end(), Key, |
| 1118 |
[](const IndexType &LHS, const KeyType &RHS) { |
| 1119 |
int CmpName = StringRef(LHS.Name).compare(RHS.Name); |
| 1120 |
if (CmpName < 0) return true; |
| 1121 |
if (CmpName > 0) return false; |
| 1122 |
if ((unsigned)LHS.Kind < (unsigned)RHS.Kind) |
| 1123 |
return true; |
| 1124 |
if ((unsigned)LHS.Kind > (unsigned)RHS.Kind) |
| 1125 |
return false; |
| 1126 |
return false; |
| 1127 |
}); |
| 1128 |
|
| 1129 |
if (Idx == Table.end() || |
| 1130 |
Key.Name != Idx->Name || |
| 1131 |
Key.Kind != Idx->Kind) |
| 1132 |
return nullptr; |
| 1133 |
return &CTable[Idx->_index]; |
| 1134 |
} |