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  // Name of the C++ struct/class type that holds table entries. The
64  // declaration of this type is not generated automatically.
65  string CppTypeName = FilterClass;
66
67  // List of the names of fields of collected records that contain the data for
68  // table entries, in the order that is used for initialization in C++.
69  //
70  // TableGen needs to know the type of the fields so that it can format
71  // the initializers correctly. It can infer the type of bit, bits, string,
72  // Intrinsic, and Instruction values.
73  //
74  // For each field of the table named xxx, TableGen will look for a field
75  // named TypeOf_xxx and use that as a more detailed description of the
76  // type of the field. This is required for fields whose type
77  // cannot be deduced automatically, such as enum fields. For example:
78  //
79  //   def MyEnum : GenericEnum {
80  //     let FilterClass = "MyEnum";
81  //     ...
82  //   }
83  //
84  //   class MyTableEntry {
85  //     MyEnum V;
86  //     ...
87  //   }
88  //
89  //   def MyTable : GenericTable {
90  //     let FilterClass = "MyTableEntry";
91  //     let Fields = ["V", ...];
92  //     string TypeOf_V = "MyEnum";
93  //   }
94  //
95  // If a string field was initialized with a code literal, TableGen will
96  // emit the code verbatim. However, if a string field was initialized
97  // in some other way, but should be interpreted as code, then a TypeOf_xxx
98  // field is necessary, with a value of "code":
99  //
100  //     string TypeOf_Predicate = "code";
101  list<string> Fields;
102
103  // (Optional) List of fields that make up the primary key.
104  list<string> PrimaryKey;
105
106  // (Optional) Name of the primary key search function.
107  string PrimaryKeyName;
108
109  // See SearchIndex.EarlyOut
110  bit PrimaryKeyEarlyOut = false;
111}
112
113// Define a record derived from this class to generate an additional search
114// index for a generic table that has been defined earlier.
115//
116// The name of the record will be used as the name of the C++ lookup function.
117class SearchIndex {
118  // Table that this search index refers to.
119  GenericTable Table;
120
121  // List of fields that make up the key.
122  list<string> Key;
123
124  // If true, the lookup function will check the first field of the key against
125  // the minimum and maximum values in the index before entering the binary
126  // search. This is convenient for tables that add extended data for a subset
127  // of a larger enum-based space, e.g. extended data about a subset of
128  // instructions.
129  //
130  // Can only be used when the first field is an integral (non-string) type.
131  bit EarlyOut = false;
132}
133
134// Legacy table type with integrated enum.
135class SearchableTable {
136  list<string> SearchableFields;
137  string EnumNameField = "Name";
138  string EnumValueField;
139}
140