include/llvm/TableGen/SearchableTable.td

   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.
  33 class 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++.
  58 class 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.
 113 class 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.
 131 class SearchableTable {
 132   list<string> SearchableFields;
 133   string EnumNameField = "Name";
 134   string EnumValueField;
 135 }