Debian Codegraph @

llvm/docs/TableGen/BackEnds.rst

raw
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 }