TensorFlow is back at Google I/O on May 14! Register now

lite/c/c_api_opaque.h

C API for TensorFlow Lite Opaque Types.

Summary

These APIs are accessors for TFLite Opaque Types. These APIs are primarily intended to be used by delegates and custom OP implementations.

This API is part of the TensorFlow Lite Extension APIs. We reserve the right to make changes to this API in future releases, potentially including non-backwards-compatible changes, on a different schedule than for the other TensorFlow Lite APIs. See https://www.tensorflow.org/guide/versions#separate_version_number_for_tensorflow_lite_extension_apis.

Note: Users of TensorFlow Lite should use

#include "tensorflow/lite/c/c_api_opaque.h"

to access the APIs documented on this page.

Typedefs
`TfLiteIntArray`	typedef `struct TfLiteIntArray`
`TfLiteOpaqueTensorBuilder`	typedef `struct TfLiteOpaqueTensorBuilder` An opaque type to create a tensor.

Functions
`TfLiteOpaqueContextAcquireSubgraphContext(struct TfLiteOpaqueContext opaque_context, int subgraph_index, TfLiteOpaqueContext *acquired_opaque_context)`	`TFL_CAPI_EXPORT TfLiteStatus` Entry point for C API AcquireSubgraphContext.
`TfLiteOpaqueContextAddTensor(TfLiteOpaqueContext context, TfLiteOpaqueTensorBuilder builder, int *new_tensor_index)`	`TFL_CAPI_EXPORT TfLiteStatus` Adds an additional tensor and configures its properties based on the provided 'builder', preserving pre-existing Tensor entries.
`TfLiteOpaqueContextGetExecutionPlan(TfLiteOpaqueContext opaque_context, TfLiteIntArray *execution_plan)`	`TFL_CAPI_EXPORT TfLiteStatus` Loads the provided `execution_plan` associated with the provided `opaque_context`.
`TfLiteOpaqueContextGetInputs(const struct TfLiteOpaqueContext opaque_context, const int inputs, int num_inputs)`	`TFL_CAPI_EXPORT TfLiteStatus` Loads into the provided '*inputs' pointer the starting address of an array of indices representing the tensors that are inputs to the subgraph that is associated with the provided 'opaque_context'.
`TfLiteOpaqueContextGetName(const struct TfLiteOpaqueContext *opaque_context)`	`TFL_CAPI_EXPORT const char *` Returns the name of the subgraph that is associated with the provided 'opaque_context'.
`TfLiteOpaqueContextGetNodeAndRegistration(struct TfLiteOpaqueContext opaque_context, int node_index, TfLiteOpaqueNode node, TfLiteRegistrationExternal *registration_external)`	`TFL_CAPI_EXPORT TfLiteStatus` Given the specified 'opaque_context' and 'node_index', load the caller's opaque 'node' and 'registration_external' pointer.
`TfLiteOpaqueContextGetNodeInitDataMmapInfo(const TfLiteOpaqueContext context, const TfLiteOpaqueNode node, int fd, int64_t custom_initial_data_offset_in_file, int64_t *custom_initial_data_size)`	`TFL_CAPI_EXPORT TfLiteStatus` Loads metadata of a TF Lite node's custom initialization data.
`TfLiteOpaqueContextGetNumNodes(const struct TfLiteOpaqueContext *opaque_context)`	`TFL_CAPI_EXPORT size_t` Returns the number of nodes associated with the provided 'opaque_context'.
`TfLiteOpaqueContextGetNumTensors(const struct TfLiteOpaqueContext *opaque_context)`	`TFL_CAPI_EXPORT size_t` Returns the number of tensors associated with the provided 'opaque_context'.
`TfLiteOpaqueContextGetOpaqueTensor(const TfLiteOpaqueContext *opaque_context, int index)`	`TFL_CAPI_EXPORT TfLiteOpaqueTensor *` Returns modifiable access to the opaque tensor that corresponds to the specified `index` and is associated with the provided `opaque_context`.
`TfLiteOpaqueContextGetOutputs(const struct TfLiteOpaqueContext opaque_context, const int outputs, int num_outputs)`	`TFL_CAPI_EXPORT TfLiteStatus` Loads into the provided '*outputs' pointer the starting address of an array of indices representing the tensors that are outputs to the subgraph that is associated with the provided 'opaque_context'.
`TfLiteOpaqueContextGetSizeOfType(TfLiteOpaqueContext context, TfLiteType type, size_t bytes)`	`TFL_CAPI_EXPORT TfLiteStatus` Populates the size in bytes of a provide 'type' into 'bytes'.
`TfLiteOpaqueContextGetVariables(const struct TfLiteOpaqueContext opaque_context, const int variables, int num_variables)`	`TFL_CAPI_EXPORT TfLiteStatus` Loads into the provided '*variables' pointer the starting address of an array of indices representing the tensors that are variables to the subgraph that is associated with the provided 'opaque_context'.
`TfLiteOpaqueContextMarkSubgraphAsDelegationSkippable(TfLiteOpaqueContext *opaque_context, int subgraph_index)`	`TFL_CAPI_EXPORT TfLiteStatus` Entry point for C API MarkSubgraphAsDelegationSkippable.
`TfLiteOpaqueContextReleaseSubgraphContext(struct TfLiteOpaqueContext *opaque_context, int subgraph_index)`	`TFL_CAPI_EXPORT TfLiteStatus` Entry point for C API ReleaseSubgraphContext.
`TfLiteOpaqueContextReplaceNodeSubsetsWithDelegateKernels(struct TfLiteOpaqueContext opaque_context, TfLiteRegistrationExternal registration_external, const TfLiteIntArray nodes_to_replace, TfLiteOpaqueDelegate opaque_delegate)`	`TFL_CAPI_EXPORT TfLiteStatus` Entry point for C API ReplaceNodeSubsetsWithDelegateKernels.
`TfLiteOpaqueContextReportError(struct TfLiteOpaqueContext opaque_context, const char format, ...)`	`TFL_CAPI_EXPORT void` Reports an error message formed by using the provided 'format' string in combination with the data provided via the unnamed arguments following the 'format' parameter ('...').
`TfLiteOpaqueContextReportErrorVa(struct TfLiteOpaqueContext opaque_context, const char format, va_list vlist)`	`TFL_CAPI_EXPORT void` Same as `TfLiteOpaqueContextReportError`, but with the variable arguments passed via a `va_list` instead of directly.
`TfLiteOpaqueContextResizeTensor(TfLiteOpaqueContext context, TfLiteOpaqueTensor tensor, TfLiteIntArray *new_size)`	`TFL_CAPI_EXPORT TfLiteStatus` Resizes the provided 'tensor' that is associated with the provided 'context' so that the 'tensor's shape matches the dimensionality specified via the provided 'new_size' array.
`TfLiteOpaqueNodeGetBuiltinData(const TfLiteOpaqueNode *opaque_node)`	`TFL_CAPI_EXPORT void *` Returns the builtin data associated with the provided 'opaque_node'.
`TfLiteOpaqueNodeGetCustomInitialData(const TfLiteOpaqueNode opaque_node, const void init_data, int size)`	`TFL_CAPI_EXPORT TfLiteStatus` Loads into the provided '*init_data' pointer the address of the custom init data associated with the provided 'opaque_node'.
`TfLiteOpaqueNodeGetInput(const TfLiteOpaqueContext opaque_context, const TfLiteOpaqueNode opaque_node, int index)`	`TFL_CAPI_EXPORT const TfLiteOpaqueTensor *` Returns the input tensor of the given node.
`TfLiteOpaqueNodeGetInputTensorIndex(const TfLiteOpaqueNode *opaque_node, int index_of_input)`	`TFL_CAPI_EXPORT int` Given an 'index_of_input', which must be in the range of [0, N), where N is the number of input tensors of the provided 'opaque_node', returns the (global) index of the tensor that holds the input.
`TfLiteOpaqueNodeGetOutput(TfLiteOpaqueContext opaque_context, const TfLiteOpaqueNode opaque_node, int index)`	`TFL_CAPI_EXPORT TfLiteOpaqueTensor *` Returns the output tensor of the given node.
`TfLiteOpaqueNodeGetOutputTensorIndex(const TfLiteOpaqueNode *opaque_node, int index_of_output)`	`TFL_CAPI_EXPORT int` Given an 'index_of_output', which must be in the range of [0, N), where N is the number of output tensors of the provided 'opaque_node', returns the (global) index of the tensor that holds the output.
`TfLiteOpaqueNodeGetUserData(const TfLiteOpaqueNode *opaque_node)`	`TFL_CAPI_EXPORT void *` Returns opaque data provided by the node implementer.
`TfLiteOpaqueNodeInputs(const TfLiteOpaqueNode opaque_node, const int inputs, int num_inputs)`	`TFL_CAPI_EXPORT TfLiteStatus` Loads into the provided '*inputs' pointer the starting address of an array of indices representing the tensors that are inputs of the provided 'opaque_node'.
`TfLiteOpaqueNodeNumberOfInputs(const TfLiteOpaqueNode *opaque_node)`	`TFL_CAPI_EXPORT int` Gets the number of input tensors of the provided 'opaque_node'.
`TfLiteOpaqueNodeNumberOfOutputs(const TfLiteOpaqueNode *opaque_node)`	`TFL_CAPI_EXPORT int` Gets the number of output tensors of the provided 'opaque_node'.
`TfLiteOpaqueNodeOutputs(const TfLiteOpaqueNode opaque_node, const int outputs, int num_outputs)`	`TFL_CAPI_EXPORT TfLiteStatus` Loads into the provided '*outputs' pointer the starting address of an array of indices representing the tensors that are outputs of the provided 'opaque_node'.
`TfLiteOpaqueNodeTemporaries(const TfLiteOpaqueNode opaque_node, const int temporaries, int num_temporaries)`	`TFL_CAPI_EXPORT TfLiteStatus` Loads into the provided '*temporaries' pointer the starting address of an array of indices representing the temporary tensors associated with the provided 'opaque_node'.
`TfLiteOpaqueTensorBuilderCreate()`	`TfLiteOpaqueTensorBuilder *` Creates an opaque tensor builder object.
`TfLiteOpaqueTensorBuilderDelete(TfLiteOpaqueTensorBuilder *builder)`	`void` Deletes an opaque tensor builder object.
`TfLiteOpaqueTensorBuilderSetAllocationType(TfLiteOpaqueTensorBuilder *builder, TfLiteAllocationType allocation_type)`	`TfLiteOpaqueTensorBuilder *` Sets the allocation type of the provided 'builder' to the provided 'allocation_type'.
`TfLiteOpaqueTensorBuilderSetData(TfLiteOpaqueTensorBuilder builder, void data)`	`TfLiteOpaqueTensorBuilder *` Sets the raw data of the provided 'builder' to the provided 'data'.
`TfLiteOpaqueTensorBuilderSetQuantization(TfLiteOpaqueTensorBuilder *builder, TfLiteQuantization quantization)`	`TfLiteOpaqueTensorBuilder *` Sets the quantization of the provided 'builder' to the provided 'quantization'.
`TfLiteOpaqueTensorBuilderSetQuantizationParams(TfLiteOpaqueTensorBuilder *builder, TfLiteQuantizationParams params)`	`TfLiteOpaqueTensorBuilder *` Sets the quantization params of the provided 'builder' to the provided 'params'.
`TfLiteOpaqueTensorBuilderSetType(TfLiteOpaqueTensorBuilder *builder, TfLiteType type)`	`TfLiteOpaqueTensorBuilder *` Sets the 'TfLiteType' of the provided 'builder' to the provided 'type'.
`TfLiteOpaqueTensorByteSize(const TfLiteOpaqueTensor *opaque_tensor)`	`TFL_CAPI_EXPORT size_t` Returns the size of the underlying data in bytes.
`TfLiteOpaqueTensorCopyFromBuffer(TfLiteOpaqueTensor opaque_tensor, const void input_data, size_t input_data_size)`	`TFL_CAPI_EXPORT TfLiteStatus` Copies from the provided input buffer into the tensor's buffer.
`TfLiteOpaqueTensorCopyToBuffer(const TfLiteOpaqueTensor opaque_tensor, void output_data, size_t output_data_size)`	`TFL_CAPI_EXPORT TfLiteStatus` Copies to the provided output buffer from the tensor's buffer.
`TfLiteOpaqueTensorData(const TfLiteOpaqueTensor *opaque_tensor)`	`TFL_CAPI_EXPORT void *` Returns a pointer to the underlying data buffer.
`TfLiteOpaqueTensorDim(const TfLiteOpaqueTensor *opaque_tensor, int32_t dim_index)`	`TFL_CAPI_EXPORT int32_t` Returns the length of the tensor in the "dim_index" dimension.
`TfLiteOpaqueTensorGetAllocationStrategy(const TfLiteOpaqueTensor *t)`	`TFL_CAPI_EXPORT TfLiteAllocationStrategy` Returns a tensor data allocation strategy.
`TfLiteOpaqueTensorGetAllocationType(const TfLiteOpaqueTensor *opaque_tensor)`	`TFL_CAPI_EXPORT TfLiteAllocationType` Returns the 'opaque_tensor's allocation type.
`TfLiteOpaqueTensorGetBufferAddressStability(const TfLiteOpaqueTensor *t)`	`TFL_CAPI_EXPORT TfLiteRunStability` Returns how stable a tensor data buffer address is across runs.
`TfLiteOpaqueTensorGetDataKnownStep(const TfLiteOpaqueTensor *t)`	`TFL_CAPI_EXPORT TfLiteRunStep` Returns the operation step when the data of a tensor is populated.
`TfLiteOpaqueTensorGetDataStability(const TfLiteOpaqueTensor *t)`	`TFL_CAPI_EXPORT TfLiteRunStability` Returns how stable a tensor data values are across runs.
`TfLiteOpaqueTensorGetDimSignature(const TfLiteOpaqueTensor opaque_tensor, int32_t dim_index, int32_t dim_length)`	`TFL_CAPI_EXPORT TfLiteStatus` Loads into the provided 'dim_length' the length of the tensor in the 'dim_index' signature dimension or -1 if that dimension has unknown length.
`TfLiteOpaqueTensorGetNumDimsSignature(const TfLiteOpaqueTensor opaque_tensor, int32_t num_dims)`	`TFL_CAPI_EXPORT TfLiteStatus` Loads into the provided 'num_dims' the number of dimensions that the tensor's signature has.
`TfLiteOpaqueTensorGetQuantization(const TfLiteOpaqueTensor *opaque_tensor)`	`TFL_CAPI_EXPORT TfLiteQuantization` Returns the 'opaque_tensor's quantization information.
`TfLiteOpaqueTensorGetQuantizationParams(const TfLiteOpaqueTensor *opaque_tensor)`	`TFL_CAPI_EXPORT TfLiteQuantizationParams` Returns the 'opaque_tensor's quantization parameters.
`TfLiteOpaqueTensorGetShapeKnownStep(const TfLiteOpaqueTensor *t)`	`TFL_CAPI_EXPORT TfLiteRunStep` Returns the operation step when the shape of a tensor is computed.
`TfLiteOpaqueTensorGetString(const TfLiteOpaqueTensor tensor, int index, const char str, int len)`	`TfLiteStatus` Stores the address of the n-th (denoted by the provided 'index') string contained in the provided 'tensor' in the provided '*str' pointer.
`TfLiteOpaqueTensorGetStringCount(const TfLiteOpaqueTensor *tensor)`	`int` Returns the number of strings stored in the provided 'tensor'.
`TfLiteOpaqueTensorIsVariable(const TfLiteOpaqueTensor *opaque_tensor)`	`TFL_CAPI_EXPORT int` Returns 'non-zero' if the provided 'opaque_tensor' is a variable, and returns zero otherwise.
`TfLiteOpaqueTensorName(const TfLiteOpaqueTensor *opaque_tensor)`	`TFL_CAPI_EXPORT const char *` Returns the (null-terminated) name of the tensor.
`TfLiteOpaqueTensorNumDims(const TfLiteOpaqueTensor *opaque_tensor)`	`TFL_CAPI_EXPORT int32_t` Returns the number of dimensions that the tensor has.
`TfLiteOpaqueTensorType(const TfLiteOpaqueTensor *opaque_tensor)`	`TFL_CAPI_EXPORT TfLiteType` Returns the type of a tensor element.
`TfLiteOpaqueTensorWriteString(TfLiteOpaqueTensor tensor, const char str, int len)`	`TfLiteStatus` Writes the string pointed to by the provided 'str' pointer of length 'len' into the provided 'tensor'.
`TfLiteOpaqueTensorWriteStrings(TfLiteOpaqueTensor tensor, const char const str_array, int str_array_len, const int str_n_len)`	`TfLiteStatus` Writes the array of strings specified by 'str_array' into the specified 'tensor'.

Typedefs

TfLiteIntArray

struct TfLiteIntArray TfLiteIntArray

TfLiteOpaqueTensorBuilder

struct TfLiteOpaqueTensorBuilder TfLiteOpaqueTensorBuilder

An opaque type to create a tensor.

Functions

TfLiteOpaqueContextAcquireSubgraphContext

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueContextAcquireSubgraphContext(
  struct TfLiteOpaqueContext *opaque_context,
  int subgraph_index,
  TfLiteOpaqueContext **acquired_opaque_context
)

Entry point for C API AcquireSubgraphContext.

Retrieves the corresponding TfLiteOpaqueContext of a subgraph given a subgraph index and switches to the delegate context for this subgraph. If an invalid subgraph index is given, then returns kTfLiteError.

NOTE: This function is expected to be paired with TfLiteOpaqueContextReleaseSubgraphContext() once the delegate preparation is done and/or the delegate context functions are no longer needed.

TfLiteOpaqueContextAddTensor

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueContextAddTensor(
  TfLiteOpaqueContext *context,
  TfLiteOpaqueTensorBuilder *builder,
  int *new_tensor_index
)

Adds an additional tensor and configures its properties based on the provided 'builder', preserving pre-existing Tensor entries.

If non-null, the value pointed to by 'new_tensor_index' will be set to the index of the new tensor. Returns 'kTfLiteOk' when the tensor has been added successfully. Returns 'kTfLiteError' in case of failure.

TfLiteOpaqueContextGetExecutionPlan

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueContextGetExecutionPlan(
  TfLiteOpaqueContext *opaque_context,
  TfLiteIntArray **execution_plan
)

Loads the provided execution_plan associated with the provided opaque_context.

Returns kTfLiteOk if the execution_plan was successfully loaded. A return value different from kTfLiteOk indicates a failure and the execution_plan will be left in an unspecified state.

TfLiteOpaqueContextGetInputs

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueContextGetInputs(
  const struct TfLiteOpaqueContext *opaque_context,
  const int **inputs,
  int *num_inputs
)

Loads into the provided '*inputs' pointer the starting address of an array of indices representing the tensors that are inputs to the subgraph that is associated with the provided 'opaque_context'.

The length of the array is loaded into the provided 'num_inputs' pointer. Returns 'kTfLiteOk' in case of success. Any other return value indicates a failure and will leave 'inputs' and 'num_inputs' in an unspecified state. Calls to 'SetInputs' on the associated subgraph invalidate the loaded pointers.

TfLiteOpaqueContextGetName

TFL_CAPI_EXPORT const char * TfLiteOpaqueContextGetName(
  const struct TfLiteOpaqueContext *opaque_context
)

Returns the name of the subgraph that is associated with the provided 'opaque_context'.

Typically the returned pointer will remain valid throughout the lifetime of the subgraph, but may be invalidated by a call to 'Subgraph::SetName'.

TfLiteOpaqueContextGetNodeAndRegistration

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueContextGetNodeAndRegistration(
  struct TfLiteOpaqueContext *opaque_context,
  int node_index,
  TfLiteOpaqueNode **node,
  TfLiteRegistrationExternal **registration_external
)

Given the specified 'opaque_context' and 'node_index', load the caller's opaque '*node' and '*registration_external' pointer.

Return 'kTfLiteOk' if both the '*node' as well as the '*registration_external' have been loaded correctly. Any other return code indicates a failure and both '*node' as well as '*registration_external' will be in an unspecified state.

A caller can obtain a node's index by calling 'TfLiteOpaqueContextGetExecutionPlan', which provides an array of node indices, sorted in execution order. A node index might also come from the data structures passed to the delegate kernel's callback parameters, like the delegate parameters data structure passed to the 'init' callback that contains an array of node indices that are meant to be handled by the delegate kernel.

This function is expected to be called from within a delegate callback, like 'Prepare', or a delegate kernel callback (i.e., a callback registered with a 'TfLiteRegistrationExternal' object).

The loaded '*node' and '*registration_external' pointers will generally remain valid for the lifetime of the associated 'opaque_context', but can be invalidated through API calls where delegates get un-applied, like API calls that modify the model graph via a delegate, or if input tensors get re-sized.

TfLiteOpaqueContextGetNodeInitDataMmapInfo

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueContextGetNodeInitDataMmapInfo(
  const TfLiteOpaqueContext *context,
  const TfLiteOpaqueNode *node,
  int *fd,
  int64_t *custom_initial_data_offset_in_file,
  int64_t *custom_initial_data_size
)

Loads metadata of a TF Lite node's custom initialization data.

Specifically:

Loads into the supplied 'fd' the file descriptor of the file that stores the 'node's custom initialization data. This output parameter will be loaded if the TF Lite runtime has access to the file descriptor, though this is not always the case, e.g. if a client provides a tflite::Model directly to the TF Lite runtime. If 'fd' can be loaded then 'kTfLiteOk' will be returned, otherwise 'kTfLiteError' is returned.
Loads into the supplied 'custom_initial_data_offset_in_file' pointer the offset of the 'node's custom init data in the file associated with 'fd'. This output parameter will be set to -1 if the 'node' does not have custom init data set.
Loads into the supplied 'custom_initial_data_size' the size of the custom initialization data. This output parameter will be set to -1 if the 'node' does not have custom init data set.

Returns 'kTfLiteOk' when 'fd' has been loaded successfully and 'kTfLiteError' otherwise. Note that this means that 'kTfLiteOk' can be returned, even if the 'node' does not have custom init data set.

TfLiteOpaqueContextGetNumNodes

TFL_CAPI_EXPORT size_t TfLiteOpaqueContextGetNumNodes(
  const struct TfLiteOpaqueContext *opaque_context
)

Returns the number of nodes associated with the provided 'opaque_context'.

TfLiteOpaqueContextGetNumTensors

TFL_CAPI_EXPORT size_t TfLiteOpaqueContextGetNumTensors(
  const struct TfLiteOpaqueContext *opaque_context
)

Returns the number of tensors associated with the provided 'opaque_context'.

TfLiteOpaqueContextGetOpaqueTensor

TFL_CAPI_EXPORT TfLiteOpaqueTensor * TfLiteOpaqueContextGetOpaqueTensor(
  const TfLiteOpaqueContext *opaque_context,
  int index
)

Returns modifiable access to the opaque tensor that corresponds to the specified index and is associated with the provided opaque_context.

This requires the index to be between 0 and N - 1, where N is the number of tensors in the model.

Typically the tensors associated with the context would be set during the initialization of the interpreter that the context belongs to, through a mechanism like the InterpreterBuilder, and remain unchanged throughout the lifetime of the interpreter. However, there are some circumstances in which the pointer may not remain valid throughout the lifetime of the interpreter, because calls to AddTensors on the interpreter invalidate the returned pointer.

The ownership of the tensor remains with the TFLite runtime, meaning the caller should not deallocate the pointer.

TfLiteOpaqueContextGetOutputs

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueContextGetOutputs(
  const struct TfLiteOpaqueContext *opaque_context,
  const int **outputs,
  int *num_outputs
)

Loads into the provided '*outputs' pointer the starting address of an array of indices representing the tensors that are outputs to the subgraph that is associated with the provided 'opaque_context'.

The length of the array is loaded into the provided 'num_outputs' pointer. Returns 'kTfLiteOk' in case of success. Any other return value indicates a failure and will leave 'outputs' and 'num_outputs' in an unspecified state. Calls to 'SetOutputs' on the associated subgraph invalidate the loaded pointers.

TfLiteOpaqueContextGetSizeOfType

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueContextGetSizeOfType(
  TfLiteOpaqueContext *context,
  TfLiteType type,
  size_t *bytes
)

Populates the size in bytes of a provide 'type' into 'bytes'.

Returns 'kTfLiteOk' for valid types, and 'kTfLiteError' otherwise.

TfLiteOpaqueContextGetVariables

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueContextGetVariables(
  const struct TfLiteOpaqueContext *opaque_context,
  const int **variables,
  int *num_variables
)

Loads into the provided '*variables' pointer the starting address of an array of indices representing the tensors that are variables to the subgraph that is associated with the provided 'opaque_context'.

The length of the array is loaded into the provided 'num_variables' pointer. Returns 'kTfLiteOk' in case of success. Any other return value indicates a failure and will leave 'variables' and 'num_variables' in an unspecified state. Calls to 'SetVariables' on the associated subgraph invalidate the loaded pointers.

TfLiteOpaqueContextMarkSubgraphAsDelegationSkippable

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueContextMarkSubgraphAsDelegationSkippable(
  TfLiteOpaqueContext *opaque_context,
  int subgraph_index
)

Entry point for C API MarkSubgraphAsDelegationSkippable.

Marks the subgraph with the given index as "delegation-skippable". Returns kTfLiteOk if the given subgraph index is valid and is successfully marked as delegation-skippable, and an error status if the subgraph index is invalid. If a subgraph is delegation-skippable, then the subgraph will be handled by a specific TfLiteOpaqueDelegate that is already supposed to be aware of this condition, and therefore, TfLiteInterpreter can skip invoking ModifyGraphWithDelegate on this subgraph.

NOTE: This function is expected to be called only when the subgraph that subgraph_index is pointing to should be skipped by interpreter::ModifyGraphWithDelegate (e.g. the subgraph is part of the list of callee subgraphs of the same control flow node, and all of those callees are supported by the same delegate at once).

For example, this function can be used when the delegate is handling control flow ops such as while ops. For instance, a while op has a condition subgraph indexed at i and a body subgraph indexed at j. The op can be delegated when the following conditions hold:

The delegate supports while op
Both condition subgraph i and body subgraph j can be fully delegated to the delegate.

Then if the delegate decides to support the while node along with both body and condition subgraphs, it should mark subgraphs i and j skippable so that those two subgraphs won't be delegated to another delegate.

WARNING: It is the delegate's responsibility to define when to skip Subgraph::ModifyGraphWithDelegate, to check for any edge cases (i.e. multiple references to the subgraph that subgraph_index is pointing to), and to mark a subgraph as skippable by using this function.

TfLiteOpaqueContextReleaseSubgraphContext

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueContextReleaseSubgraphContext(
  struct TfLiteOpaqueContext *opaque_context,
  int subgraph_index
)

Entry point for C API ReleaseSubgraphContext.

Releases the corresponding TfLiteOpaqueContext by switching back to the TFLite kernel context for this specified subgraph.

NOTE: This function is expected to be used after TfLiteOpaqueContextAcquireSubgraphContext() once the delegate preparation is done and/or the delegate context functions are no longer needed.

TfLiteOpaqueContextReplaceNodeSubsetsWithDelegateKernels

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueContextReplaceNodeSubsetsWithDelegateKernels(
  struct TfLiteOpaqueContext *opaque_context,
  TfLiteRegistrationExternal *registration_external,
  const TfLiteIntArray *nodes_to_replace,
  TfLiteOpaqueDelegate *opaque_delegate
)

Entry point for C API ReplaceNodeSubsetsWithDelegateKernels.

Replaces the specified nodes_to_replace that are associated with the provided opaque_context with delegate kernels. The provided registration_external represents the delegate kernel and will be used for each node subset that will be delegate to the provided opaque_delegate.

The TF Lite runtime will take ownership of the registration_external and will delete it when the associated opaque_context gets destroyed.

The ownership of the nodes_to_replace and the opaque_delegate remains with the caller.

TfLiteOpaqueContextReportError

TFL_CAPI_EXPORT void TfLiteOpaqueContextReportError(
  struct TfLiteOpaqueContext *opaque_context,
  const char *format,
  ...
)

Reports an error message formed by using the provided 'format' string in combination with the data provided via the unnamed arguments following the 'format' parameter ('...').

The intended usage and behavior is the same as with 'printf' with regards to how the data and the formatting string interact. E.g. 'TfLiteOpaqueContextReportError(opaque_context, "a=%d b=%d", a, b);'

The provided 'opaque_context' will be used for reporting the resulting error message.

Note that TF Lite clients can use macros like 'TF_LITE_OPAQUE_ENSURE' to check for certain conditions to be true, and print an error message if the condition does not hold. Direct usage of this function from application code should therefore be rare.

TfLiteOpaqueContextReportErrorVa

TFL_CAPI_EXPORT void TfLiteOpaqueContextReportErrorVa(
  struct TfLiteOpaqueContext *opaque_context,
  const char *format,
  va_list vlist
)

Same as TfLiteOpaqueContextReportError, but with the variable arguments passed via a va_list instead of directly.

Callers that receive an ellipsis and want to forward it to to the opaque context error reporting API can add the ellipsis content to a va_list and then call TfLiteOpaqueContextReportErrorVa. E.g.:

void MyErrorReporter(struct TfLiteOpaqueContext* opaque_context,
                                 const char* format, ...) {
  va_list vlist;
  va_start(vlist, format);
  TfLiteOpaqueContextReportErrorVa(opaque_context, format, vlist);
  va_end(vlist);
}

TfLiteOpaqueContextResizeTensor

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueContextResizeTensor(
  TfLiteOpaqueContext *context,
  TfLiteOpaqueTensor *tensor,
  TfLiteIntArray *new_size
)

Resizes the provided 'tensor' that is associated with the provided 'context' so that the 'tensor's shape matches the dimensionality specified via the provided 'new_size' array.

Returns 'kTfLiteOk' in case of success. Any other return value indicates a failure and will leave the 'tensor' in an unspecified state. The TF Lite runtime takes ownership of the 'new_size' array, even in case of failure.

TfLiteOpaqueNodeGetBuiltinData

TFL_CAPI_EXPORT void * TfLiteOpaqueNodeGetBuiltinData(
  const TfLiteOpaqueNode *opaque_node
)

Returns the builtin data associated with the provided 'opaque_node'.

The builtin init data associated with a node would typically be set during the creation of the associated interpreter, through a mechanism like the interpreter builder that loads a TFLite model and initialises the interpreter's nodes accordingly. Under these conditions the returned address remains valid throughout the lifetime of the 'opaque_node'.

TfLiteOpaqueNodeGetCustomInitialData

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueNodeGetCustomInitialData(
  const TfLiteOpaqueNode *opaque_node,
  const void **init_data,
  int *size
)

Loads into the provided '*init_data' pointer the address of the custom init data associated with the provided 'opaque_node'.

The length of data is loaded into the provided 'size' pointer. Returns 'kTfLiteOk' in case of success. Any other return value indicates a failure and will leave 'init_data' and 'size' in an unspecified state.

The custom init data associated with a node would typically be set during the creation of the associated interpreter, through a mechanism like the interpreter builder that loads a TFLite model and initialises the interpreter's nodes accordingly. Under these conditions the returned address remains valid throughout the lifetime of the 'opaque_node'.

TfLiteOpaqueNodeGetInput

TFL_CAPI_EXPORT const TfLiteOpaqueTensor * TfLiteOpaqueNodeGetInput(
  const TfLiteOpaqueContext *opaque_context,
  const TfLiteOpaqueNode *opaque_node,
  int index
)

Returns the input tensor of the given node.

TfLiteOpaqueNodeGetInputTensorIndex

TFL_CAPI_EXPORT int TfLiteOpaqueNodeGetInputTensorIndex(
  const TfLiteOpaqueNode *opaque_node,
  int index_of_input
)

Given an 'index_of_input', which must be in the range of [0, N), where N is the number of input tensors of the provided 'opaque_node', returns the (global) index of the tensor that holds the input.

Returns -1 if 'index_of_input' is not within the [0, N) range.

TfLiteOpaqueNodeGetOutput

TFL_CAPI_EXPORT TfLiteOpaqueTensor * TfLiteOpaqueNodeGetOutput(
  TfLiteOpaqueContext *opaque_context,
  const TfLiteOpaqueNode *opaque_node,
  int index
)

Returns the output tensor of the given node.

TfLiteOpaqueNodeGetOutputTensorIndex

TFL_CAPI_EXPORT int TfLiteOpaqueNodeGetOutputTensorIndex(
  const TfLiteOpaqueNode *opaque_node,
  int index_of_output
)

Given an 'index_of_output', which must be in the range of [0, N), where N is the number of output tensors of the provided 'opaque_node', returns the (global) index of the tensor that holds the output.

Returns -1 if 'index_of_output' is not within the [0, N) range.

TfLiteOpaqueNodeGetUserData

TFL_CAPI_EXPORT void * TfLiteOpaqueNodeGetUserData(
  const TfLiteOpaqueNode *opaque_node
)

Returns opaque data provided by the node implementer.

The value returned from this function is the value that was returned from the init callback that was passed to TfLiteRegistrationExternalSetInit.

TfLiteOpaqueNodeInputs

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueNodeInputs(
  const TfLiteOpaqueNode *opaque_node,
  const int **inputs,
  int *num_inputs
)

Loads into the provided '*inputs' pointer the starting address of an array of indices representing the tensors that are inputs of the provided 'opaque_node'.

The input tensors associated with a node would typically be set during the creation of the associated interpreter, through a mechanism like the interpreter builder that loads a TFLite model and initialises the interpreter's nodes accordingly. Under these conditions the loaded address remains valid throughout the lifetime of the 'opaque_node'.

TfLiteOpaqueNodeNumberOfInputs

TFL_CAPI_EXPORT int TfLiteOpaqueNodeNumberOfInputs(
  const TfLiteOpaqueNode *opaque_node
)

Gets the number of input tensors of the provided 'opaque_node'.

TfLiteOpaqueNodeNumberOfOutputs

TFL_CAPI_EXPORT int TfLiteOpaqueNodeNumberOfOutputs(
  const TfLiteOpaqueNode *opaque_node
)

Gets the number of output tensors of the provided 'opaque_node'.

TfLiteOpaqueNodeOutputs

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueNodeOutputs(
  const TfLiteOpaqueNode *opaque_node,
  const int **outputs,
  int *num_outputs
)

Loads into the provided '*outputs' pointer the starting address of an array of indices representing the tensors that are outputs of the provided 'opaque_node'.

The output tensors associated with a node would typically be set during the creation of the associated interpreter, through a mechanism like the interpreter builder that loads a TFLite model and initialises the interpreter's nodes accordingly. Under these conditions the loaded address remains valid throughout the lifetime of the 'opaque_node'.

TfLiteOpaqueNodeTemporaries

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueNodeTemporaries(
  const TfLiteOpaqueNode *opaque_node,
  const int **temporaries,
  int *num_temporaries
)

Loads into the provided '*temporaries' pointer the starting address of an array of indices representing the temporary tensors associated with the provided 'opaque_node'.

The length of the array is loaded into the provided 'num_temporaries' pointer. Returns 'kTfLiteOk' in case of success. Any other return value indicates a failure and will leave 'temporaries' and 'num_temporaries' in an unspecified state.

The temporary tensors associated with a node would typically be set during the creation of the associated interpreter, through a mechanism like the interpreter builder that loads a TFLite model and initialises the interpreter's nodes accordingly. Under these conditions the loaded address remains valid throughout the lifetime of the 'opaque_node'.

TfLiteOpaqueTensorBuilderCreate

TfLiteOpaqueTensorBuilder * TfLiteOpaqueTensorBuilderCreate()

Creates an opaque tensor builder object.

TfLiteOpaqueTensorBuilderDelete

void TfLiteOpaqueTensorBuilderDelete(
  TfLiteOpaqueTensorBuilder *builder
)

Deletes an opaque tensor builder object.

TfLiteOpaqueTensorBuilderSetAllocationType

TfLiteOpaqueTensorBuilder * TfLiteOpaqueTensorBuilderSetAllocationType(
  TfLiteOpaqueTensorBuilder *builder,
  TfLiteAllocationType allocation_type
)

Sets the allocation type of the provided 'builder' to the provided 'allocation_type'.

The 'allocation_type' must be one of the following: 'kTfLiteDynamic', 'kTfLiteArenaRw' or 'kTfLiteArenaRwPersistent'. If the provided 'allocation_type' is not one of those values then 'TfLiteOpaqueContextAddTensor' will return an error. Returns the address of the provided 'builder', so that builder calls can be chained together.

TfLiteOpaqueTensorBuilderSetData

TfLiteOpaqueTensorBuilder * TfLiteOpaqueTensorBuilderSetData(
  TfLiteOpaqueTensorBuilder *builder,
  void *data
)

Sets the raw data of the provided 'builder' to the provided 'data'.

Returns the address of the provided 'builder', so that builder calls can be chained together.

TfLiteOpaqueTensorBuilderSetQuantization

TfLiteOpaqueTensorBuilder * TfLiteOpaqueTensorBuilderSetQuantization(
  TfLiteOpaqueTensorBuilder *builder,
  TfLiteQuantization quantization
)

Sets the quantization of the provided 'builder' to the provided 'quantization'.

Returns the address of the provided 'builder', so that builder calls can be chained together.

TfLiteOpaqueTensorBuilderSetQuantizationParams

TfLiteOpaqueTensorBuilder * TfLiteOpaqueTensorBuilderSetQuantizationParams(
  TfLiteOpaqueTensorBuilder *builder,
  TfLiteQuantizationParams params
)

Sets the quantization params of the provided 'builder' to the provided 'params'.

Returns the address of the provided 'builder', so that builder calls can be chained together.

TfLiteOpaqueTensorBuilderSetType

TfLiteOpaqueTensorBuilder * TfLiteOpaqueTensorBuilderSetType(
  TfLiteOpaqueTensorBuilder *builder,
  TfLiteType type
)

Sets the 'TfLiteType' of the provided 'builder' to the provided 'type'.

Returns the address of the provided 'builder', so that builder calls can be chained together.

TfLiteOpaqueTensorByteSize

TFL_CAPI_EXPORT size_t TfLiteOpaqueTensorByteSize(
  const TfLiteOpaqueTensor *opaque_tensor
)

Returns the size of the underlying data in bytes.

TfLiteOpaqueTensorCopyFromBuffer

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueTensorCopyFromBuffer(
  TfLiteOpaqueTensor *opaque_tensor,
  const void *input_data,
  size_t input_data_size
)

Copies from the provided input buffer into the tensor's buffer.

TfLiteOpaqueTensorCopyToBuffer

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueTensorCopyToBuffer(
  const TfLiteOpaqueTensor *opaque_tensor,
  void *output_data,
  size_t output_data_size
)

Copies to the provided output buffer from the tensor's buffer.

TfLiteOpaqueTensorData

TFL_CAPI_EXPORT void * TfLiteOpaqueTensorData(
  const TfLiteOpaqueTensor *opaque_tensor
)

Returns a pointer to the underlying data buffer.

TfLiteOpaqueTensorDim

TFL_CAPI_EXPORT int32_t TfLiteOpaqueTensorDim(
  const TfLiteOpaqueTensor *opaque_tensor,
  int32_t dim_index
)

Returns the length of the tensor in the "dim_index" dimension.

TfLiteOpaqueTensorGetAllocationStrategy

TFL_CAPI_EXPORT TfLiteAllocationStrategy TfLiteOpaqueTensorGetAllocationStrategy(
  const TfLiteOpaqueTensor *t
)

Returns a tensor data allocation strategy.

TfLiteOpaqueTensorGetAllocationType

TFL_CAPI_EXPORT TfLiteAllocationType TfLiteOpaqueTensorGetAllocationType(
  const TfLiteOpaqueTensor *opaque_tensor
)

Returns the 'opaque_tensor's allocation type.

TfLiteOpaqueTensorGetBufferAddressStability

TFL_CAPI_EXPORT TfLiteRunStability TfLiteOpaqueTensorGetBufferAddressStability(
  const TfLiteOpaqueTensor *t
)

Returns how stable a tensor data buffer address is across runs.

TfLiteOpaqueTensorGetDataKnownStep

TFL_CAPI_EXPORT TfLiteRunStep TfLiteOpaqueTensorGetDataKnownStep(
  const TfLiteOpaqueTensor *t
)

Returns the operation step when the data of a tensor is populated.

TfLiteOpaqueTensorGetDataStability

TFL_CAPI_EXPORT TfLiteRunStability TfLiteOpaqueTensorGetDataStability(
  const TfLiteOpaqueTensor *t
)

Returns how stable a tensor data values are across runs.

TfLiteOpaqueTensorGetDimSignature

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueTensorGetDimSignature(
  const TfLiteOpaqueTensor *opaque_tensor,
  int32_t dim_index,
  int32_t *dim_length
)

Loads into the provided 'dim_length' the length of the tensor in the 'dim_index' signature dimension or -1 if that dimension has unknown length.

Returns 'kTfLiteOk' if 'dim_length' was successfully loaded. Any other return code indicates an error and 'dim_length' won't be loaded.

TfLiteOpaqueTensorGetNumDimsSignature

TFL_CAPI_EXPORT TfLiteStatus TfLiteOpaqueTensorGetNumDimsSignature(
  const TfLiteOpaqueTensor *opaque_tensor,
  int32_t *num_dims
)

Loads into the provided 'num_dims' the number of dimensions that the tensor's signature has.

Returns 'kTfLiteOk' if 'num_dims' was successfully loaded. Any other return code indicates an error and 'num_dims' won't be loaded.

A tensor's dimension signature encodes shapes with unknown dimensions with -1. E.g. for a tensor with three dimensions, whose first dimension has an unknown size, and the second and third dimension have a size of 2, the dimension signature is [-1,2,2], and 'TfLiteOpaqueTensorGetNumDimsSignature' loads 3 into 'num_dims'. If the tensor does not have its dimension signature field set then 'num_dims' is set to -1.

TfLiteOpaqueTensorGetQuantization

TFL_CAPI_EXPORT TfLiteQuantization TfLiteOpaqueTensorGetQuantization(
  const TfLiteOpaqueTensor *opaque_tensor
)

Returns the 'opaque_tensor's quantization information.

TfLiteOpaqueTensorGetQuantizationParams

TFL_CAPI_EXPORT TfLiteQuantizationParams TfLiteOpaqueTensorGetQuantizationParams(
  const TfLiteOpaqueTensor *opaque_tensor
)

Returns the 'opaque_tensor's quantization parameters.

TfLiteOpaqueTensorGetShapeKnownStep

TFL_CAPI_EXPORT TfLiteRunStep TfLiteOpaqueTensorGetShapeKnownStep(
  const TfLiteOpaqueTensor *t
)

Returns the operation step when the shape of a tensor is computed.

TfLiteOpaqueTensorGetString

TfLiteStatus TfLiteOpaqueTensorGetString(
  const TfLiteOpaqueTensor *tensor,
  int index,
  const char **str,
  int *len
)

Stores the address of the n-th (denoted by the provided 'index') string contained in the provided 'tensor' in the provided '*str' pointer.

Stores the length of the string in the provided '*len' argument.

Returns 'kTfLiteOk' if '*str' and '*len' have been set successfully. Any other return value indicates a failure, which leaves '*str' and '*len' in an unspecified state.

The range of valid indices is defined by the half open interval [0, N), where N == TfLiteOpaqueTensorGetStringCount(tensor).

Note that 'str' is not guaranteed to be null-terminated. Also note that this function will not create a copy of the underlying string data. The data is owned by the 'tensor'.

TfLiteOpaqueTensorGetStringCount

int TfLiteOpaqueTensorGetStringCount(
  const TfLiteOpaqueTensor *tensor
)

Returns the number of strings stored in the provided 'tensor'.

Returns -1 in case of failure.

TfLiteOpaqueTensorIsVariable

TFL_CAPI_EXPORT int TfLiteOpaqueTensorIsVariable(
  const TfLiteOpaqueTensor *opaque_tensor
)

Returns 'non-zero' if the provided 'opaque_tensor' is a variable, and returns zero otherwise.

TfLiteOpaqueTensorName

TFL_CAPI_EXPORT const char * TfLiteOpaqueTensorName(
  const TfLiteOpaqueTensor *opaque_tensor
)

Returns the (null-terminated) name of the tensor.

TfLiteOpaqueTensorNumDims

TFL_CAPI_EXPORT int32_t TfLiteOpaqueTensorNumDims(
  const TfLiteOpaqueTensor *opaque_tensor
)

Returns the number of dimensions that the tensor has.

Returns -1 in case the 'opaque_tensor' does not have its dimensions property set.

TfLiteOpaqueTensorType

TFL_CAPI_EXPORT TfLiteType TfLiteOpaqueTensorType(
  const TfLiteOpaqueTensor *opaque_tensor
)

Returns the type of a tensor element.

TfLiteOpaqueTensorWriteString

TfLiteStatus TfLiteOpaqueTensorWriteString(
  TfLiteOpaqueTensor *tensor,
  const char *str,
  int len
)

Writes the string pointed to by the provided 'str' pointer of length 'len' into the provided 'tensor'.

The string provided via 'str' is copied into the 'tensor'. Returns 'kTfLiteOk' in case of success. Any other return value indicates a failure.

Note that calling 'TfLiteOpaqueTensorWriteString' deallocates any previously stored data in the 'tensor'. E.g. suppose 't' denotes a 'TfLiteOpaqueTensor*', then calling 'TfLiteOpaqueTensorWriteString(t, "AB", 2)' followed by a call to 'TfLiteOpaqueTensorWriteString(t, "CD", 2)' will lead to 't' containing 'CD', not 'ABCD'.

'TfLiteOpaqueTensorWriteString' is a convenience function for the use case of writing a single string to a tensor and its effects are identical to calling 'TfLiteOpaqueTensorWriteStrings' with an array of a single string.

TfLiteOpaqueTensorWriteStrings

TfLiteStatus TfLiteOpaqueTensorWriteStrings(
  TfLiteOpaqueTensor *tensor,
  const char *const *str_array,
  int str_array_len,
  const int *str_n_len
)

Writes the array of strings specified by 'str_array' into the specified 'tensor'.

The strings provided via the 'str_array' are being copied into the 'tensor'. Returns 'kTfLiteOk' in case of success. Any other return value indicates a failure.

The provided 'str_array_len' must denote the length of 'str_array' and 'str_n_len[i]' must denote the length of the i-th string.

The provided strings don't need to be null terminated and may contain embedded null characters. The amount of bytes copied into the 'tensor' is entirely determined by 'str_n_len[i]' and it is the caller's responsibility to set this value correctly to avoid undefined behavior.

Also note that calling 'TfLiteOpaqueTensorWriteStrings' deallocates any previously stored data in the 'tensor'.