nnpackage/spec/30_custom_op.md

   1 # Custom Operators
   2
   3 This document explains about custom operator and how custom op is represented in nnpackage.
   4
   5 ## What is custom operator?
   6
   7 Custom operator(hereafter custom op) is used to provide a new operator implementation.
   8 It can be anything that does not exist in current runtime implementation.
   9
  10 You can use custom operator for several use cases, possible use cases are:
  11
  12 - when an operator in tensorflow is not supported in nnfw runtime
  13 - when an operator is supported, however, you would like to use your own implementation
  14   - it may be for optimization, by grouping several operators into one super operator.
  15
  16 ## Custom op in model
  17
  18 nnpackage will support several kinds of models.
  19 Currently the only type is tflite.
  20
  21 ### tflite
  22
  23 If you're using `tflite` format, it is same format to tensorflow lite.
  24
  25 You can generate `tflite` model with custom op using `tflite_convert`.
  26 Please find the documentation in tensorflow official site.
  27
  28 ## Custom op kernel implementation
  29
  30 You need to provide the kernel of custom op in the following form:
  31
  32 ```
  33 /*
  34  * Custom kernel evaluation function
  35  *
  36  * param[in] params custom operation parameters
  37  * param[in] userdata pointer to user-specified buffer( kernel instance specific )
  38  */
  39 typedef void (*nnfw_custom_eval)(nnfw_custom_kernel_params *params, char *userdata,
  40                                  size_t userdata_size);
  41
  42 ```
  43
  44 The structures and relevant APIs are defined in nnfw APIs.
  45 Please see `nnfw_experimental.h` for detail.
  46
  47 You can find example in `nnfw` repository.
  48
  49 Custom op kernel implementation is stored in nnpackage in form of prebuilt library.
  50
  51 It is example nnpackage structure for `FillFrom`:
  52
  53 ```
  54 FillFrom
  55 ├── FillFrom.tflite
  56 ├── custom_op
  57 │   ├── libFillFrom.armv7l-linux.debug.a
  58 │   └── libFillFrom.armv7l-linux.release.a
  59 └── metadata
  60     └── MANIFEST
  61 ```
  62
  63 All custom operator libraries are put under `{nnpackage_root}/custom_op/lib{customop_name}.{arch}-{os}.{buildtype}.a`.
  64
  65 ## How to use custom op in app
  66
  67 To use custom op, the app has to register the operators with `nnfw_register_custom_op_info`.
  68
  69
  70 ```
  71 /*
  72  * custom operation registration info
  73  */
  74 typedef struct
  75 {
  76   nnfw_custom_eval eval_function;
  77 } custom_kernel_registration_info;
  78
  79 NNFW_STATUS nnfw_register_custom_op_info(nnfw_session *session, const char *id,
  80                                          custom_kernel_registration_info *info)
  81 ```
  82
  83 Please find sample app in `nnfw` repository
  84
  85 The `id` should be unique in an app.
  86