TableGen backends are at the core of TableGen’s functionality. The source files
provide the semantics to a generated (in memory) structure, but it’s up to the
backend to print this out in a way that is meaningful to the user (normally a
C program including a file or a textual list of warnings, options and error
messages).

TableGen is used by both LLVM and Clang with very different goals. LLVM uses it
as a way to automate the generation of massive amounts of information regarding
instructions, schedules, cores and architecture features. Some backends generate
output that is consumed by more than one source file, so they need to be created
in a way that is easy to use pre-processor tricks. Some backends can also print
C code structures, so that they can be directly included as-is.

Clang, on the other hand, uses it mainly for diagnostic messages (errors,
warnings, tips) and attributes, so more on the textual end of the scale.

This document is raw. Each section below needs three sub-sections: description
of its purpose with a list of users, output generated from generic input, and
finally why it needed a new backend (in case there’s something similar).

Overall, each backend will take the same TableGen file type and transform into
similar output for different targets/uses. There is an implicit contract between
the TableGen files, the back-ends and their users.

For instance, a global contract is that each back-end produces macro-guarded
sections. Based on whether the file is included by a header or a source file,
or even in which context of each file the include is being used, you have
todefine a macro just before including it, to get the right output:

#define GET_REGINFO_TARGET_DESC#include"ARMGenRegisterInfo.inc"

And just part of the generated file would be included. This is useful if
you need the same information in multiple formats (instantiation, initialization,
getter/setter functions, etc) from the same source TableGen file without having
to re-compile the TableGen file multiple times.

Sometimes, multiple macros might be defined before the same include file to
output multiple blocks:

The macros will be undef’d automatically as they’re used, in the include file.

On all LLVM back-ends, the llvm-tblgen binary will be executed on the root
TableGen file <Target>.td, which should include all others. This guarantees
that all information needed is accessible, and that no duplication is needed
in the TableGen files.

Purpose: CodeEmitterGen uses the descriptions of instructions and their fields to
construct an automated code emitter: a function that, given a MachineInstr,
returns the (currently, 32-bit unsigned) value of the instruction.

Purpose: This tablegen backend is responsible for emitting a description of a target
register file for a code generator. It uses instances of the Register,
RegisterAliases, and RegisterClass classes to gather this information.

Purpose: Emits a target specifier matcher for
converting parsed assembly operands in the MCInst structures. It also
emits a matcher for custom operand parsing. Extensive documentation is
written on the AsmMatcherEmitter.cpp file.

Output: Assembler parsers’ matcher functions, declarations, etc.

Usage: Used in back-ends’ AsmParser/<Target>AsmParser.cpp for
building the AsmParser class.

Purpose: This class parses the Schedule.td file and produces an API that
can be used to reason about whether an instruction can be added to a packet
on a VLIW architecture. The class internally generates a deterministic finite
automaton (DFA) that models all possible mappings of machine instructions
to functional units as instructions are added to a packet.

Purpose: This tablegen backend emits code for use by the “fast”
instruction selection algorithm. See the comments at the top of
lib/CodeGen/SelectionDAG/FastISel.cpp for background. This file
scans through the target’s tablegen instruction-info files
and extracts instructions with obvious-looking patterns, and it emits
code to look up these instructions by type and operator.

Purpose: Creates AttrParserStringSwitches.inc, which contains
StringSwitch::Case statements for parser-related string switches. Each switch
is given its own macro (such as CLANG_ATTR_ARG_CONTEXT_LIST, or
CLANG_ATTR_IDENTIFIER_ARG_LIST), which is expected to be defined before
including AttrParserStringSwitches.inc, and undefined after.

Purpose: Creates AttrList.inc, which is used when a list of semantic
attribute identifiers is required. For instance, AttrKinds.h includes this
file to generate the list of attr::Kind enumeration values. This list is
separated out into multiple categories: attributes, inheritable attributes, and
inheritable parameter attributes. This categorization happens automatically
based on information in Attr.td and is used to implement the classof
functionality required for dyn_cast and similar APIs.

Purpose: Creates AttrParsedAttrImpl.inc, which is used by
AttributeList.cpp to implement several functions on the AttributeList
class. This functionality is implemented via the AttrInfoMapParsedAttrInfo
array, which contains one element per parsed attribute object.

Until we get a step-by-step HowTo for writing TableGen backends, you can at
least grab the boilerplate (build system, new files, etc.) from Clang’s
r173931.

TODO: How they work, how to write one. This section should not contain details
about any particular backend, except maybe -print-enums as an example. This
should highlight the APIs in TableGen/Record.h.