1 /* Copyright 2018 The TensorFlow Authors. All Rights Reserved. 2 3 Licensed under the Apache License, Version 2.0 (the "License"); 4 you may not use this file except in compliance with the License. 5 You may obtain a copy of the License at 6 7 http://www.apache.org/licenses/LICENSE-2.0 8 9 Unless required by applicable law or agreed to in writing, software 10 distributed under the License is distributed on an "AS IS" BASIS, 11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 See the License for the specific language governing permissions and 13 limitations under the License. 14 ==============================================================================*/ 15 #ifndef TENSORFLOW_LITE_C_C_API_EXPERIMENTAL_H_ 16 #define TENSORFLOW_LITE_C_C_API_EXPERIMENTAL_H_ 17 18 #include "tensorflow/lite/builtin_ops.h" 19 #include "tensorflow/lite/c/c_api.h" 20 #include "tensorflow/lite/c/common.h" 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif // __cplusplus 25 26 /// Resets all variable tensors to zero. 27 /// 28 /// WARNING: This is an experimental API and subject to change. 29 TFL_CAPI_EXPORT extern TfLiteStatus TfLiteInterpreterResetVariableTensors( 30 TfLiteInterpreter* interpreter); 31 32 /// Adds an op registration for a builtin operator. 33 /// 34 /// Op registrations are used to map ops referenced in the flatbuffer model 35 /// to executable function pointers (`TfLiteRegistration`s). 36 /// 37 /// NOTE: The interpreter will make a shallow copy of `registration` internally, 38 /// so the caller should ensure that its contents (function pointers, etc...) 39 /// remain valid for the duration of the interpreter's lifetime. A common 40 /// practice is making the provided `TfLiteRegistration` instance static. 41 /// 42 /// Code that uses this function should NOT call 43 /// `TfLiteInterpreterOptionsSetOpResolver' on the same options object. 44 /// 45 /// WARNING: This is an experimental API and subject to change. 46 TFL_CAPI_EXPORT void TfLiteInterpreterOptionsAddBuiltinOp( 47 TfLiteInterpreterOptions* options, TfLiteBuiltinOperator op, 48 const TfLiteRegistration* registration, int32_t min_version, 49 int32_t max_version); 50 51 /// Adds an op registration for a custom operator. 52 /// 53 /// Op registrations are used to map ops referenced in the flatbuffer model 54 /// to executable function pointers (`TfLiteRegistration`s). 55 /// 56 /// NOTE: The interpreter will make a shallow copy of `registration` internally, 57 /// so the caller should ensure that its contents (function pointers, etc...) 58 /// remain valid for the duration of any created interpreter's lifetime. A 59 /// common practice is making the provided `TfLiteRegistration` instance static. 60 /// 61 /// Code that uses this function should NOT call 62 /// `TfLiteInterpreterOptionsSetOpResolver' on the same options object. 63 /// 64 /// WARNING: This is an experimental API and subject to change. 65 TFL_CAPI_EXPORT void TfLiteInterpreterOptionsAddCustomOp( 66 TfLiteInterpreterOptions* options, const char* name, 67 const TfLiteRegistration* registration, int32_t min_version, 68 int32_t max_version); 69 70 /// Registers callbacks for resolving builtin or custom operators. 71 /// 72 /// The `TfLiteInterpreterOptionsSetOpResolver` function provides an alternative 73 /// method for registering builtin ops and/or custom ops, by providing operator 74 /// resolver callbacks. Unlike using `TfLiteInterpreterOptionsAddBuiltinOp` 75 /// and/or `TfLiteInterpreterOptionsAddAddCustomOp`, these let you register all 76 /// the operators in a single call. 77 /// 78 /// Code that uses this function should NOT call 79 /// `TfLiteInterpreterOptionsAddBuiltin' or 80 /// `TfLiteInterpreterOptionsAddCustomOp' on the same options object. 81 /// 82 /// WARNING: This is an experimental API and subject to change. 83 void TfLiteInterpreterOptionsSetOpResolver( 84 TfLiteInterpreterOptions* options, 85 const TfLiteRegistration* (*find_builtin_op)(void* user_data, 86 TfLiteBuiltinOperator op, 87 int version), 88 const TfLiteRegistration* (*find_custom_op)(void* user_data, 89 const char* custom_op, 90 int version), 91 void* op_resolver_user_data); 92 93 /// Returns a new interpreter using the provided model and options, or null on 94 /// failure, where the model uses only the operators explicitly added to the 95 /// options. This is the same as `TFLiteInterpreterCreate` from `c_api.h`, 96 /// except that the only operators that are supported are the ones registered 97 /// in `options` via calls to `TfLiteInterpreterOptionsSetOpResolver`, 98 /// `TfLiteInterpreterOptionsAddBuiltinOp`, and/or 99 /// `TfLiteInterpreterOptionsAddCustomOp`. 100 /// 101 /// * `model` must be a valid model instance. The caller retains ownership of 102 /// the object, and can destroy it immediately after creating the interpreter; 103 /// the interpreter will maintain its own reference to the underlying model 104 /// data. 105 /// * `options` should not be null. The caller retains ownership of the object, 106 /// and can safely destroy it immediately after creating the interpreter. 107 /// 108 /// NOTE: The client *must* explicitly allocate tensors before attempting to 109 /// access input tensor data or invoke the interpreter. 110 /// 111 /// WARNING: This is an experimental API and subject to change. 112 TFL_CAPI_EXPORT extern TfLiteInterpreter* 113 TfLiteInterpreterCreateWithSelectedOps(const TfLiteModel* model, 114 const TfLiteInterpreterOptions* options); 115 116 /// Enable or disable the NN API delegate for the interpreter (true to enable). 117 /// 118 /// WARNING: This is an experimental API and subject to change. 119 TFL_CAPI_EXPORT extern void TfLiteInterpreterOptionsSetUseNNAPI( 120 TfLiteInterpreterOptions* options, bool enable); 121 122 /// Enable or disable CPU fallback for the interpreter (true to enable). 123 /// If enabled, TfLiteInterpreterInvoke will do automatic fallback from 124 /// executing with delegate(s) to regular execution without delegates 125 /// (i.e. on CPU). 126 /// 127 /// Allowing the fallback is suitable only if both of the following hold: 128 /// - The caller is known not to cache pointers to tensor data across 129 /// TfLiteInterpreterInvoke calls. 130 /// - The model is not stateful (no variables, no LSTMs) or the state isn't 131 /// needed between batches. 132 /// 133 /// When delegate fallback is enabled, TfLiteInterpreterInvoke will 134 /// behave as follows: 135 /// If one or more delegates were set in the interpreter options 136 /// (see TfLiteInterpreterOptionsAddDelegate), 137 /// AND inference fails, 138 /// then the interpreter will fall back to not using any delegates. 139 /// In that case, the previously applied delegate(s) will be automatically 140 /// undone, and an attempt will be made to return the interpreter to an 141 /// invokable state, which may invalidate previous tensor addresses, 142 /// and the inference will be attempted again, using input tensors with 143 /// the same value as previously set. 144 /// 145 /// WARNING: This is an experimental API and subject to change. 146 TFL_CAPI_EXPORT extern void TfLiteInterpreterOptionsSetEnableDelegateFallback( 147 TfLiteInterpreterOptions* options, bool enable); 148 149 #ifdef __cplusplus 150 } // extern "C" 151 #endif // __cplusplus 152 153 #endif // TENSORFLOW_LITE_C_C_API_EXPERIMENTAL_H_ 154