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  // For each field of the table named XXX, TableGen will look for a value
71  // called TypeOf_XXX and use that as a more detailed description of the
72  // type of the field if present. This is required for fields whose type
73  // cannot be deduced automatically, such as enum fields. For example:
74  //
75  //   def MyEnum : GenericEnum {
76  //     let FilterClass = "MyEnum";
77  //     ...
78  //   }
79  //
80  //   class MyTableEntry {
81  //     MyEnum V;
82  //     ...
83  //   }
84  //
85  //   def MyTable : GenericTable {
86  //     let FilterClass = "MyTableEntry";
87  //     let Fields = ["V", ...];
88  //     GenericEnum TypeOf_V = MyEnum;
89  //   }
90  //
91  // Fields of type bit, bits<N>, string, Intrinsic, and Instruction (or
92  // derived classes of those) are supported natively.
93  //
94  // Additionally, fields of type `code` can appear, where the value is used
95  // verbatim as an initializer. However, these fields cannot be used as
96  // search keys.
97  list<string> Fields;
98
99  // (Optional) List of fields that make up the primary key.
100  list<string> PrimaryKey;
101
102  // (Optional) Name of the primary key search function.
103  string PrimaryKeyName;
104
105  // See SearchIndex.EarlyOut
106  bit PrimaryKeyEarlyOut = 0;
107}
108
109// Define a record derived from this class to generate an additional search
110// index for a generic table that has been defined earlier.
111//
112// The name of the record will be used as the name of the C++ lookup function.
113class SearchIndex {
114  // Table that this search index refers to.
115  GenericTable Table;
116
117  // List of fields that make up the key.
118  list<string> Key;
119
120  // If true, the lookup function will check the first field of the key against
121  // the minimum and maximum values in the index before entering the binary
122  // search. This is convenient for tables that add extended data for a subset
123  // of a larger enum-based space, e.g. extended data about a subset of
124  // instructions.
125  //
126  // Can only be used when the first field is an integral (non-string) type.
127  bit EarlyOut = 0;
128}
129
130// Legacy table type with integrated enum.
131class SearchableTable {
132  list<string> SearchableFields;
133  string EnumNameField = "Name";
134  string EnumValueField;
135}
136