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