Doxygen Book
_GstTensorFilterFramework Struct Reference

Tensor_Filter Subplugin definition. More...

#include <nnstreamer_plugin_api_filter.h>

Collaboration diagram for _GstTensorFilterFramework:

Public Attributes

uint64_t version
 
int(* open )(const GstTensorFilterProperties *prop, void **private_data)
 
void(* close )(const GstTensorFilterProperties *prop, void **private_data)
 
union {
   struct {
      char *   name
 
      int   allow_in_place
 
      int   allocate_in_invoke
 
      int   run_without_model
 
      int   verify_model_path
 
      const GstTensorFilterFrameworkStatistics *   statistics
 
      int(*   invoke_NN )(const
         GstTensorFilterProperties
         *prop, void **private_data,
         const GstTensorMemory *input,
         GstTensorMemory *output)
 
      int(*   getInputDimension )(const
         GstTensorFilterProperties
         *prop, void **private_data,
         GstTensorsInfo *info)
 
      int(*   getOutputDimension )(const
         GstTensorFilterProperties
         *prop, void **private_data,
         GstTensorsInfo *info)
 
      int(*   setInputDimension )(const
         GstTensorFilterProperties
         *prop, void **private_data,
         const GstTensorsInfo *in_info,
         GstTensorsInfo *out_info)
 
      void(*   destroyNotify )(void **private_data, void *data)
 
      int(*   reloadModel )(const
         GstTensorFilterProperties
         *prop, void **private_data)
 
      int(*   handleEvent )(event_ops ops,
         GstTensorFilterFrameworkEventData
         *data)
 
      int(*   checkAvailability )(accl_hw hw)
 
      int(*   allocateInInvoke )(void **private_data)
 
   } 
 Tensor_Filter Subplugin definition Version 0. More...
 
   struct {
      int(*   invoke )(const
         GstTensorFilterFramework *self,
         GstTensorFilterProperties
         *prop, void *private_data,
         const GstTensorMemory *input,
         GstTensorMemory *output)
 
      int(*   getFrameworkInfo )(const
         GstTensorFilterFramework *self,
         const
         GstTensorFilterProperties
         *prop, void *private_data,
         GstTensorFilterFrameworkInfo
         *fw_info)
 
      int(*   getModelInfo )(const
         GstTensorFilterFramework *self,
         const
         GstTensorFilterProperties
         *prop, void *private_data,
         model_info_ops ops,
         GstTensorsInfo *in_info,
         GstTensorsInfo *out_info)
 
      int(*   eventHandler )(const
         GstTensorFilterFramework *self,
         const
         GstTensorFilterProperties
         *prop, void *private_data,
         event_ops ops,
         GstTensorFilterFrameworkEventData
         *data)
 
      void *   subplugin_data
 
   } 
 Tensor_Filter Subplugin definition Version 1. More...
 
}; 
 Distinct elements between two versions of the subplugin interfaces. More...
 

Detailed Description

Tensor_Filter Subplugin definition.

Common callback parameters: prop Filter properties. Read Only. private_data Subplugin's private data. Set this (*private_data = XXX) if you want to change filter->private_data.

Definition at line 249 of file nnstreamer_plugin_api_filter.h.

Member Data Documentation

◆ @53

union { ... }

Distinct elements between two versions of the subplugin interfaces.

◆ allocate_in_invoke

int _GstTensorFilterFramework::allocate_in_invoke

TRUE(nonzero) if invoke_NN is going to allocate output ptr by itself and return the address via output ptr. Do not change this value after cap negotiation is complete (or the stream has been started).

Definition at line 286 of file nnstreamer_plugin_api_filter.h.

◆ allocateInInvoke

int(* _GstTensorFilterFramework::allocateInInvoke) (void **private_data)

Optional. Tensor-filter will call it when allocate_in_invoke is set to TRUE. This check if the provided model for the framework supports allocation at invoke or not. If this is not defined, then the value of allocate_in_invoke is assumed to be final for all models.

Parameters
[in]private_dataA subplugin may save its internal private data here.
Returns
0 if supported. -errno if not supported.

Definition at line 378 of file nnstreamer_plugin_api_filter.h.

◆ allow_in_place

int _GstTensorFilterFramework::allow_in_place

TRUE(nonzero) if in-place transfer of input-to-output is allowed. Not supported in main, yet

Definition at line 285 of file nnstreamer_plugin_api_filter.h.

◆ checkAvailability

int(* _GstTensorFilterFramework::checkAvailability) (accl_hw hw)

Optional. Check if the provided hardware accelerator is supported. This check is static or dynamic based on framework support. Positive response of this check does not guarantee successful running of model with this accelerator. The static check can be performed without opening the framework.

Parameters
[in]hwbackend accelerator hardware
Returns
0 if supported. -errno if not supported.

Definition at line 371 of file nnstreamer_plugin_api_filter.h.

◆ close

void(* _GstTensorFilterFramework::close) (const GstTensorFilterProperties *prop, void **private_data)

Optional. Tensor-filter will not call other callbacks after calling close. Free-ing private_data is this function's responsibility. Set NULL after that.

Parameters
[in]propread-only property values.
[in/out]private_data A subplugin may save its internal private data here. The subplugin is responsible for alloc/free of this pointer. Normally, close() frees private_data and set NULL.

Definition at line 267 of file nnstreamer_plugin_api_filter.h.

◆ destroyNotify

void(* _GstTensorFilterFramework::destroyNotify) (void **private_data, void *data)

Optional. Tensor-filter will call it when 'allocate_in_invoke' flag of the framework is TRUE and allocateInInvoke also return enabled. Basically, it is called when the data element is destroyed. If it's set as NULL, g_free() will be used as a default. It will be helpful when the data pointer is included as an object of a nnfw. For instance, if the data pointer is removed when the object is gone, it occurs error. In this case, the objects should be maintained for a while first and destroyed when the data pointer is destroyed. Those kinds of logic could be defined at this method.

Parameters
[in/out]private_data A subplugin may save its internal private data here. The subplugin is responsible for alloc/free of this pointer.
[in]datathe data element.

Definition at line 346 of file nnstreamer_plugin_api_filter.h.

◆ eventHandler

int(* _GstTensorFilterFramework::eventHandler) (const GstTensorFilterFramework *self, const GstTensorFilterProperties *prop, void *private_data, event_ops ops, GstTensorFilterFrameworkEventData *data)

Mandatory callback. Runs the event corresponding to the passed operation. If ops == DESTROY_NOTIFY: Tensor-filter will call it when 'allocate_in_invoke' property of the framework is TRUE. Basically, it is called when the data element is destroyed. If it's set as NULL, g_free() will be used as a default. It will be helpful when the data pointer is included as an object of a nnfw. For instance, if the data pointer is removed when the object is gone, it occurs error. In this case, the objects should be maintained for a while first and destroyed when the data pointer is destroyed. Those kinds of logic could be defined at this method. If ops == RELOAD_MODEL: Tensor-filter will call it when a model property is newly configured. Also, 'is-updatable' property of the framework should be TRUE. This function reloads a new model passed in as argument via data. Note that it requires extra memory size enough to temporarily hold both old and new models during this function to hide the reload overhead. If ops == CUSTOM_PROP: Tensor-filter will call to update the custom properties of the subplugin. If ops == SET_INPUT_PROP: Tensor-filter will call to update the property of the subplugin. This function will take tensor info and layout as the argument. This operation can update input tensor shape, type, name and layout. If ops == SET_OUTPUT_PROP: Tensor-filter will call to update the property of the subplugin. This function will take tensor info and layout as the argument. This operation can update output tensor shape, type, name and layout. If ops == SET_ACCELERATOR: Tensor-filter will call to update the property of the subplugin. This function will take accelerator list as the argument. This operation will update the backend to be used by the corresponding subplugin. List of operations to be supported are optional. Note: In these operations, the argument 'prop' will not contain the updated information, but will be updated after the corresponding operation is succeeded.

Parameters
[in]propread-only property values
[in/out]private_data A subplugin may save its internal private data here. The subplugin is responsible for alloc/free of this pointer. (can be NULL)
[in]opsoperation to be performed
[in/out]data event data for the supported handlers (can be NULL)
Returns
0 if OK. non-zero if error. -ENOENT if operation is not supported. -EINVAL if operation is supported but provided arguments are invalid.

Definition at line 445 of file nnstreamer_plugin_api_filter.h.

◆ getFrameworkInfo

int(* _GstTensorFilterFramework::getFrameworkInfo) (const GstTensorFilterFramework *self, const GstTensorFilterProperties *prop, void *private_data, GstTensorFilterFrameworkInfo *fw_info)

Mandatory callback. Get the frameworks statically determined info. Argument 'private_data' can be NULL. If provided 'private_data' is not NULL, then some info, such as 'allocate_in_invoke', can be updated based on the model being used (inferred from the 'private_data' provided). This updated info is useful for custom filter, as some custom filter's ability to support 'allocate_in_invoke' depends on the opened model.

Parameters
[in]propread-only property values
[in]private_dataA subplugin may save its internal private data here. The subplugin is responsible for alloc/free of this pointer. This parameter can be NULL.
[out]fw_infostruct to hold frameworks info. Must be allocated by the caller (return value).
Returns
0 if OK. non-zero if error.
Note
CAUTION: private_data can be NULL if the framework is not yet opened by the caller.

Definition at line 407 of file nnstreamer_plugin_api_filter.h.

◆ getInputDimension

int(* _GstTensorFilterFramework::getInputDimension) (const GstTensorFilterProperties *prop, void **private_data, GstTensorsInfo *info)

Optional. Set NULL if not supported. Get dimension of input tensor If getInputDimension is NULL, setInputDimension must be defined. If getInputDimension is defined, it is recommended to define getOutputDimension.

Parameters
[in]propread-only property values
[in/out]private_data A subplugin may save its internal private data here. The subplugin is responsible for alloc/free of this pointer.
[out]infostructure of tensor info (return value)
Returns
0 if OK. non-zero if error.

Definition at line 303 of file nnstreamer_plugin_api_filter.h.

◆ getModelInfo

int(* _GstTensorFilterFramework::getModelInfo) (const GstTensorFilterFramework *self, const GstTensorFilterProperties *prop, void *private_data, model_info_ops ops, GstTensorsInfo *in_info, GstTensorsInfo *out_info)

Mandatory callback. Gets the model related tensor info. If ops == GET_IN_OUT_INFO, in_info would contain the input tensor info, and out_info would contain the output tensor info. If ops == SET_INPUT_INFO, in_info would contain the provided input tensor info, and out_info would contain the updated output tensor info. At least one of SET_INPUT_INFO and GET_IN_OUT_INFO operations must be supported.

Note: Tensor_Filter::main will configure input dimension from pad-cap in run-time for the sub-plugin. Then, the sub-plugin is required to return corresponding output dimension, and will call SET_INPUT_INFO operation.

Note: With SET_INPUT_INFO operation, the caller must NOT allocate or fix internal data structure based on the return value until invoke is called. GStreamer may try different dimensions before settling down.

Parameters
[in]propread-only property values
[in/out]private_data A subplugin may save its internal private data here. The subplugin is responsible for alloc/free of this pointer.
[in]opsoperation to be performed
[in/out]in_info structure of input tensor info
[out]out_infostructure of output tensor info (return value)
Returns
0 if OK. non-zero if error. -ENOENT is operation is not supported.

Definition at line 420 of file nnstreamer_plugin_api_filter.h.

◆ getOutputDimension

int(* _GstTensorFilterFramework::getOutputDimension) (const GstTensorFilterProperties *prop, void **private_data, GstTensorsInfo *info)

Optional. Set NULL if not supported. Get dimension of output tensor If getInputDimension is NULL, setInputDimension must be defined. If getInputDimension is defined, it is recommended to define getOutputDimension.

Parameters
[in]propread-only property values
[in/out]private_data A subplugin may save its internal private data here. The subplugin is responsible for alloc/free of this pointer.
[out]infostructure of tensor info (return value)
Returns
0 if OK. non-zero if error.

Definition at line 315 of file nnstreamer_plugin_api_filter.h.

◆ handleEvent

int(* _GstTensorFilterFramework::handleEvent) (event_ops ops, GstTensorFilterFrameworkEventData *data)

Optional. Runs the event corresponding to the passed operation. If ops == CHECK_HW_AVAILABILITY: tensor_filter will call to check the hw availability with custom option. List of operations to be supported are optional.

Parameters
[in]opsoperation to be performed
[in/out]data event data for the supported handlers (can be NULL)
Returns
0 if OK. non-zero if error. -ENOENT if operation is not supported. -EINVAL if operation is supported but provided arguments are invalid.

Definition at line 361 of file nnstreamer_plugin_api_filter.h.

◆ invoke

int(* _GstTensorFilterFramework::invoke) (const GstTensorFilterFramework *self, GstTensorFilterProperties *prop, void *private_data, const GstTensorMemory *input, GstTensorMemory *output)

Mandatory callback. Invoke the given network model.

Parameters
[in/out]prop property values. In the case of dynamic invoke, the output tensors info must be filled.
[in/out]private_data A subplugin may save its internal private data here. The subplugin is responsible for alloc/free of this pointer.
[in]inputThe array of input tensors. Allocated and filled by tensor_filter/main
[out]outputThe array of output tensors. Allocated by tensor_filter/main and to be filled by invoke. If allocate_in_invoke is TRUE, sub-plugin should allocate the memory block for output tensor. (data in GstTensorMemory)
Returns
0 if OK. non-zero if error.

Definition at line 395 of file nnstreamer_plugin_api_filter.h.

◆ invoke_NN

int(* _GstTensorFilterFramework::invoke_NN) (const GstTensorFilterProperties *prop, void **private_data, const GstTensorMemory *input, GstTensorMemory *output)

Mandatory callback. Invoke the given network model.

Parameters
[in]propread-only property values
[in/out]private_data A subplugin may save its internal private data here. The subplugin is responsible for alloc/free of this pointer.
[in]inputThe array of input tensors. Allocated and filled by tensor_filter/main
[out]outputThe array of output tensors. Allocated by tensor_filter/main and to be filled by invoke_NN. If allocate_in_invoke is TRUE, sub-plugin should allocate the memory block for output tensor. (data in GstTensorMemory)
Returns
0 if OK. non-zero if error.

Definition at line 292 of file nnstreamer_plugin_api_filter.h.

◆ name

char* _GstTensorFilterFramework::name

Name of the neural network framework, searchable by FRAMEWORK property

Definition at line 284 of file nnstreamer_plugin_api_filter.h.

◆ open

int(* _GstTensorFilterFramework::open) (const GstTensorFilterProperties *prop, void **private_data)

Optional. Tensor-filter will call this before any of other callbacks and will call once before calling close.

Note: If 'open' callback is not defined, then the private_data passed in other callbacks will be NULL.

Parameters
[in]propread-only property values.
[in/out]private_data A subplugin may save its internal private data here. The subplugin is responsible for alloc/free of this pointer. Normally, open() allocates memory for private_data.
Returns
0 if ok. < 0 if error.

Definition at line 257 of file nnstreamer_plugin_api_filter.h.

◆ reloadModel

int(* _GstTensorFilterFramework::reloadModel) (const GstTensorFilterProperties *prop, void **private_data)

Optional. Tensor-filter will call it when a model property is newly configured. Also, 'is-updatable' property of the framework should be TRUE. This function reloads a new model specified in the 'prop' argument. Note that it requires extra memory size enough to temporarily hold both old and new models during this function to hide the reload overhead.

Parameters
[in]propread-only property values
[in/out]private_data A subplugin may save its internal private data here. The subplugin is responsible for alloc/free of this pointer. Normally, close() frees private_data and set NULL.
Returns
0 if ok. < 0 if error.

Definition at line 353 of file nnstreamer_plugin_api_filter.h.

◆ run_without_model

int _GstTensorFilterFramework::run_without_model

TRUE(nonzero) when the neural network framework does not need a model file. Tensor-filter will run invoke_NN without model.

Definition at line 287 of file nnstreamer_plugin_api_filter.h.

◆ setInputDimension

int(* _GstTensorFilterFramework::setInputDimension) (const GstTensorFilterProperties *prop, void **private_data, const GstTensorsInfo *in_info, GstTensorsInfo *out_info)

Optional. Set Null if not supported. Tensor_Filter::main will configure input dimension from pad-cap in run-time for the sub-plugin. Then, the sub-plugin is required to return corresponding output dimension If this is NULL, both getInput/OutputDimension must be non-NULL.

When you use this, do NOT allocate or fix internal data structure based on it until invoke is called. GStreamer may try different dimensions before settling down.

Parameters
[in]propread-only property values
[in/out]private_data A subplugin may save its internal private data here. The subplugin is responsible for alloc/free of this pointer.
[in]in_infostructure of input tensor info
[out]out_infostructure of output tensor info (return value)
Returns
0 if OK. non-zero if error.

Definition at line 327 of file nnstreamer_plugin_api_filter.h.

◆ statistics

const GstTensorFilterFrameworkStatistics* _GstTensorFilterFramework::statistics

usage statistics by the framework. This is shared across all opened instances of this framework.

Definition at line 290 of file nnstreamer_plugin_api_filter.h.

◆ subplugin_data

void* _GstTensorFilterFramework::subplugin_data

This is used by tensor_filter infrastructure. Subplugin authors should NEVER update this. Only the files in /gst/nnstreamer/tensor_filter/ are allowed to access this.

Definition at line 464 of file nnstreamer_plugin_api_filter.h.

◆ verify_model_path

int _GstTensorFilterFramework::verify_model_path

TRUE(nonzero) when the NNS framework, not the sub-plugin, should verify the path of model files.

Definition at line 288 of file nnstreamer_plugin_api_filter.h.

◆ version

uint64_t _GstTensorFilterFramework::version

Version of the struct | 32bit (validity check) | 16bit (API version) | 16bit (Subplugin's internal version. Tensor-filter does not care.) | API version will be 0x0 (earlier version (_GstTensorFilterFramework_v0)) or 0x1 (newer version (_GstTensorFilterFramework_v1))

Definition at line 251 of file nnstreamer_plugin_api_filter.h.


The documentation for this struct was generated from the following file: