1//===- SearchableTable.td ----------------------------------*- tablegen -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9//
10// This file defines the key top-level classes needed to produce a reasonably
11// generic table that can be binary-searched. Three types of objects can be
12// defined using the classes in this file:
13//
14// 1. (Generic) Enums. By instantiating the GenericEnum class once, an enum with
15// the name of the def is generated. It is guarded by the preprocessor define
16// GET_name_DECL, where name is the name of the def.
17//
18// 2. (Generic) Tables and search indices. By instantiating the GenericTable
19// class once, a table with the name of the instantiating def is generated and
20// guarded by the GET_name_IMPL preprocessor guard.
21//
22// Both a primary key and additional secondary keys / search indices can also
23// be defined, which result in the generation of lookup functions. Their
24// declarations and definitions are all guarded by GET_name_DECL and
25// GET_name_IMPL, respectively, where name is the name of the underlying table.
26//
27// See AArch64SystemOperands.td and its generated header for example uses.
28//
29//===----------------------------------------------------------------------===//
30
31// Define a record derived from this class to generate a generic enum.
32//
33// The name of the record is used as the type name of the C++ enum.
34class GenericEnum {
35  // Name of a TableGen class. The enum will have one entry for each record
36  // that derives from that class.
37  string FilterClass;
38
39  // (Optional) Name of a field that is present in all collected records and
40  // contains the name of enum entries.
41  //
42  // If NameField is not set, the record names will be used instead.
43  string NameField;
44
45  // (Optional) Name of a field that is present in all collected records and
46  // contains the numerical value of enum entries.
47  //
48  // If ValueField is not set, enum values will be assigned automatically,
49  // starting at 0, according to a lexicographical sort of the entry names.
50  string ValueField;
51}
52
53// Define a record derived from this class to generate a generic table. This
54// table can have a searchable primary key, and it can also be referenced by
55// external search indices.
56//
57// The name of the record is used as the name of the global primary array of
58// entries of the table in C++.
59class GenericTable {
60  // Name of a class. The table will have one entry for each record that
61  // derives from that class.
62  string FilterClass;
63
64  // Name of the C++ struct/class type that holds table entries. The
65  // declaration of this type is not generated automatically.
66  string CppTypeName = FilterClass;
67
68  // List of the names of fields of collected records that contain the data for
69  // table entries, in the order that is used for initialization in C++.
70  //
71  // For each field of the table named XXX, TableGen will look for a value
72  // called TypeOf_XXX and use that as a more detailed description of the
73  // type of the field if present. This is required for fields whose type
74  // cannot be deduced automatically, such as enum fields. For example:
75  //
76  //   def MyEnum : GenericEnum {
77  //     let FilterClass = "MyEnum";
78  //     ...
79  //   }
80  //
81  //   class MyTableEntry {
82  //     MyEnum V;
83  //     ...
84  //   }
85  //
86  //   def MyTable : GenericTable {
87  //     let FilterClass = "MyTableEntry";
88  //     let Fields = ["V", ...];
89  //     GenericEnum TypeOf_V = MyEnum;
90  //   }
91  //
92  // Fields of type bit, bits<N>, string, Intrinsic, and Instruction (or
93  // derived classes of those) are supported natively.
94  //
95  // Additionally, fields of type `code` can appear, where the value is used
96  // verbatim as an initializer. However, these fields cannot be used as
97  // search keys.
98  list<string> Fields;
99
100  // (Optional) List of fields that make up the primary key.
101  list<string> PrimaryKey;
102
103  // (Optional) Name of the primary key search function.
104  string PrimaryKeyName;
105
106  // See SearchIndex.EarlyOut
107  bit PrimaryKeyEarlyOut = 0;
108}
109
110// Define a record derived from this class to generate an additional search
111// index for a generic table that has been defined earlier.
112//
113// The name of the record will be used as the name of the C++ lookup function.
114class SearchIndex {
115  // Table that this search index refers to.
116  GenericTable Table;
117
118  // List of fields that make up the key.
119  list<string> Key;
120
121  // If true, the lookup function will check the first field of the key against
122  // the minimum and maximum values in the index before entering the binary
123  // search. This is convenient for tables that add extended data for a subset
124  // of a larger enum-based space, e.g. extended data about a subset of
125  // instructions.
126  //
127  // Can only be used when the first field is an integral (non-string) type.
128  bit EarlyOut = 0;
129}
130
131// Legacy table type with integrated enum.
132class SearchableTable {
133  list<string> SearchableFields;
134  string EnumNameField = "Name";
135  string EnumValueField;
136}
137