interpreter.h 5.37 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

20 21 22 23 24
/*!
 * \file tvm/relay/interpreter.h
 * \brief An interpreter for Relay.
 *
 * This file implements a simple reference interpreter for Relay programs.
25
 * Given a Relay module, and a Relay expression it produces a value.
26 27
 *
 * The interpreter's values are a naive representation of the values that
28 29
 * can be produced by a Relay program and are exposed via TVM's object
 * protocol to Python for introspection and debugging.
30 31 32 33 34 35 36
 *
 * The interpreter's intent is to serve as a reference semantics for the Relay IR,
 * as well as for debugging and testing.
 */
#ifndef TVM_RELAY_INTERPRETER_H_
#define TVM_RELAY_INTERPRETER_H_

37
#include <tvm/ir/module.h>
38
#include <tvm/relay/expr.h>
39
#include <tvm/runtime/object.h>
40 41
#include <tvm/runtime/container.h>
#include <tvm/runtime/vm.h>
42 43
#include <tvm/target/target.h>

44 45 46 47 48

namespace tvm {
namespace relay {

/*!
49 50
 *\brief Create a Interpreter function that can
 *  evaluate an expression and produce a value.
51 52 53 54 55 56 57 58 59 60
 *
 * The resulting value can be passed to Python, making it easy to use
 * for testing and debugging.
 *
 * The interpreter interprets the program fragments not supported by the
 * TVM runtime, although the interpreter is naively implemented it uses
 * TVM operators for evaluating all operators.
 *
 * Our intent is that this will never be the most efficient implementation of
 * Relay's semantics, but a readable and clear one.
61 62 63 64 65
 *
 * \param mod The function module.
 * \param context The primary context that the interepreter runs on.
 * \param target Compiler target flag to compile the functions on the context.
 * \return A function that takes in an expression and returns a value.
66
 */
67
runtime::TypedPackedFunc<ObjectRef(Expr)>
68
CreateInterpreter(IRModule mod, DLContext context, Target target);
69

70 71
/*! \brief The container type of Closures used by the interpreter. */
class InterpreterClosureObj : public runtime::vm::ClosureObj {
72 73 74 75 76 77
 public:
  /*! \brief The set of free variables in the closure.
   *
   * These are the captured variables which are required for
   * evaluation when we call the closure.
   */
78
  tvm::Map<Var, ObjectRef> env;
79 80 81 82 83 84
  /*! \brief The function which implements the closure.
   *
   * \note May reference the variables contained in the env.
   */
  Function func;

85
  InterpreterClosureObj() {}
86

87
  void VisitAttrs(tvm::AttrVisitor* v) {
88 89 90 91
    v->Visit("env", &env);
    v->Visit("func", &func);
  }

92 93
  static constexpr const char* _type_key = "interpreter.Closure";
  TVM_DECLARE_FINAL_OBJECT_INFO(InterpreterClosureObj, runtime::vm::ClosureObj);
94 95
};

96
class InterpreterClosure : public runtime::vm::Closure {
97
 public:
98 99 100
  TVM_DLL InterpreterClosure(tvm::Map<Var, ObjectRef> env, Function func);
  TVM_DEFINE_OBJECT_REF_METHODS(InterpreterClosure, runtime::vm::Closure,
                                InterpreterClosureObj);
101
};
102

103
/*! \brief The container type of RecClosure. */
104
class RecClosureObj : public Object {
105 106
 public:
  /*! \brief The closure. */
107
  InterpreterClosure clos;
108 109 110
  /*! \brief variable the closure bind to. */
  Var bind;

111
  RecClosureObj() {}
112

Tianqi Chen committed
113
  void VisitAttrs(tvm::AttrVisitor* v) {
114 115 116 117
    v->Visit("clos", &clos);
    v->Visit("bind", &bind);
  }

118 119
  static constexpr const char* _type_key = "interpreter.RecClosure";
  TVM_DECLARE_FINAL_OBJECT_INFO(RecClosureObj, Object);
120 121
};

122
class RecClosure : public ObjectRef {
123
 public:
124 125
  TVM_DLL RecClosure(InterpreterClosure clos, Var bind);
  TVM_DEFINE_OBJECT_REF_METHODS(RecClosure, ObjectRef, RecClosureObj);
126
};
127

128
struct RefValueObj : Object {
129
  mutable ObjectRef value;
130

131
  RefValueObj() {}
132

133
  void VisitAttrs(tvm::AttrVisitor* v) {
134 135 136 137
    v->Visit("value", &value);
  }

  static constexpr const char* _type_key = "relay.RefValue";
138
  TVM_DECLARE_FINAL_OBJECT_INFO(RefValueObj, Object);
139 140
};

141
class RefValue : public ObjectRef {
142
 public:
143 144
  TVM_DLL RefValue(ObjectRef val);
  TVM_DEFINE_OBJECT_REF_METHODS(RefValue, ObjectRef, RefValueObj);
145
};
146

147
struct ConstructorValueObj : Object {
148
  int32_t tag;
149

150
  tvm::Array<ObjectRef> fields;
151

152 153 154
  /*! \brief Optional field tracking ADT constructor. */
  Constructor constructor;

155
  void VisitAttrs(tvm::AttrVisitor* v) {
156
    v->Visit("tag", &tag);
157
    v->Visit("fields", &fields);
158
    v->Visit("constructor", &constructor);
159 160 161
  }

  static constexpr const char* _type_key = "relay.ConstructorValue";
162
  TVM_DECLARE_FINAL_OBJECT_INFO(ConstructorValueObj, Object);
163 164
};

165
class ConstructorValue : public ObjectRef {
166
 public:
167 168 169 170 171
  TVM_DLL ConstructorValue(int32_t tag,
                           tvm::Array<ObjectRef> fields,
                           Constructor construtor = {});

  TVM_DEFINE_OBJECT_REF_METHODS(ConstructorValue, ObjectRef, ConstructorValueObj);
172
};
173

174 175 176
}  // namespace relay
}  // namespace tvm
#endif  // TVM_RELAY_INTERPRETER_H_