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