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