runtime/onert/api/include/nnfw_experimental.h

   1 /*
   2  * Copyright (c) 2019 Samsung Electronics Co., Ltd. All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __NNFW_EXPERIMENTAL_H__
  18 #define __NNFW_EXPERIMENTAL_H__
  19
  20 #include "nnfw.h"
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 // Used for custom kernel development
  27
  28 /*
  29  * operand type, used only for custom operations
  30  */
  31 typedef struct
  32 {
  33   nnfw_tensorinfo type;
  34   void *allocation;
  35 } nnfw_operand;
  36
  37 /*
  38  * Used as input to custom operation eval function
  39  */
  40 typedef struct
  41 {
  42   size_t ninputs;
  43   nnfw_operand *inputs;
  44
  45   size_t noutputs;
  46   nnfw_operand *outputs;
  47 } nnfw_custom_kernel_params;
  48
  49 /*
  50  * Custom kernel evaluation function
  51  *
  52  * param[in] params custom operation parameters
  53  * param[in] userdata pointer to user-specified buffer( kernel instance specific )
  54  */
  55 typedef void (*nnfw_custom_eval)(nnfw_custom_kernel_params *params, char *userdata,
  56                                  size_t userdata_size);
  57
  58 /*
  59  * custom operation registration info
  60  */
  61 typedef struct
  62 {
  63   nnfw_custom_eval eval_function;
  64 } custom_kernel_registration_info;
  65
  66 NNFW_STATUS nnfw_register_custom_op_info(nnfw_session *session, const char *id,
  67                                          custom_kernel_registration_info *info);
  68
  69 /**
  70  * @brief Get the input tensor index by name
  71  *
  72  * This function finds an input tensor of the given name.
  73  * If found, the index value is set to the address that @c index points to, and returns
  74  * @c NNFW_STATUS_NO_ERROR. Otherwise, @c index is unchanged and returns @c NNFW_STATUS_ERROR .
  75  *
  76  * @note If two or more input tensors are of the same name, the one with the lowest index is always
  77  *       returned.
  78  *
  79  * @param[in]  session    the session object
  80  * @param[in]  tensorname the name of the tensor to find, a null terminated char pointer string
  81  * @param[out] index      the index to be ret
  82  * @return     @c NNFW_STATUS_NO_ERROR if successful
  83  */
  84 NNFW_STATUS nnfw_input_tensorindex(nnfw_session *session, const char *tensorname, uint32_t *index);
  85
  86 /**
  87  * @brief Get the input tensor index by name
  88  *
  89  * This function finds an input tensor of the given name.
  90  * If found, the index value is set to the address that @c index points to, and returns
  91  * @c NNFW_STATUS_NO_ERROR. Otherwise, @c index is unchanged and returns @c NNFW_STATUS_ERROR .
  92  *
  93  * @note If two or more input tensors are of the same name, the one with the lowest index is always
  94  *       returned.
  95  *
  96  * @param[in]  session    the session object
  97  * @param[in]  tensorname the name of the tensor to find, a null terminated char pointer string
  98  * @param[out] index      the index to be ret
  99  * @return     @c NNFW_STATUS_NO_ERROR if successful
 100  */
 101 NNFW_STATUS nnfw_output_tensorindex(nnfw_session *session, const char *tensorname, uint32_t *index);
 102
 103 /**
 104  * @brief Set the backend for each operation in the session
 105  *
 106  * This function assigns backends (acl_cl, acl_neon, cpu) to each operation in the session.
 107  * If successful,the function returns @c NNFW_STATUS_NO_ERROR. Otherwise, the function returns
 108  * @c NNFW_STATUS_ERROR.
 109  *
 110  * @note The argument specifying backends must be in the format
 111  *       "OP_BACKEND_MAP=\"0=acl_cl;1=cpu;2=acl_cl\"".
 112  *
 113  * @param[in]  session          the session object
 114  * @param[in]  backend_settings String containing backend assignments indexed by operation sequence
 115  * @return     @c NNFW_STATUS_NO_ERROR if successful
 116  */
 117 NNFW_STATUS nnfw_set_backends_per_operation(nnfw_session *session, const char *backend_settings);
 118
 119 /*
 120  * Prepare session to be ready for inference
 121  * This phase may finalize model compilation, scheduling, and additional settings.
 122  *
 123  * @param session the session to be prepared
 124  * @return NNFW_STATUS_NO_ERROR if successful
 125  */
 126 NNFW_STATUS nnfw_prepare_pipeline(nnfw_session *session, const char *map_file_path = nullptr);
 127
 128 /**
 129  * @brief     Set input buffer
 130  *
 131  * This function must be called after {@link nnfw_prepare_pipeline}, \p inputs given to this
 132  * function can be reused for many inferences. \p lengths must be greater or equal than the operand
 133  * requires. if you give empty \p inputs to this function, then this function will join all threads.
 134  *
 135  * @param[in] session Session to the input is to be set
 136  * @param[in] inputs  Raw buffers for input, it must be \p std::vector<void *> type pointer for
 137  * multiple input model
 138  * @param[in] lengths Size of bytes of input buffers, it must be \p std::vector<uint32_t> type
 139  * pointer for multiple input model
 140  *
 141  * @return    @c NNFW_STATUS_NO_ERROR if successful
 142  */
 143 NNFW_STATUS nnfw_push_pipeline_input(nnfw_session *session, void *inputs, void *lengths);
 144
 145 /**
 146  * @brief       Get last outputs of partitioned model in session
 147  *
 148  * This function must be called after {@link nnfw_prepare_pipeline}, \p outputs given to this
 149  * function must be cleared for memory management.
 150  *
 151  * @param[in]   session Session from last outputs is to be extracted
 152  * @param[out]  outputs Raw buffer for outputs, it must be \p std::vector<void *> type pointer for
 153  * multiple output model
 154  *
 155  * @return      @c NNFW_STATUS_NO_ERROR if successful
 156  */
 157 NNFW_STATUS nnfw_pop_pipeline_output(nnfw_session *session, void *outputs);
 158
 159 /**
 160  *  Training C APIs
 161  *
 162  * Training APIs are designed to be used in the following order for training
 163  * 1. nnfw_train_prepare
 164  * 2. nnfw_train_set_input, nnfw_train_set_expected for inputs & expected outputs
 165  * 3. nnfw_train
 166  * 4. nnfw_train_get_loss
 167  *
 168  * If you want to inference after training with the same session, you can use the following order
 169  * 1. nnfw_set_input
 170  * 2. nnfw_set_output
 171  * 3. nnfw_run
 172  */
 173
 174 //////////////////////////////////////////////
 175 // Essential APIs for training
 176 //////////////////////////////////////////////
 177 typedef enum
 178 {
 179   NNFW_TRAIN_LOSS_MEAN_SQUARED_ERROR = 0,
 180   NNFW_TRAIN_LOSS_CATEGORICAL_CROSSENTROPY = 1,
 181 } NNFW_TRAIN_LOSS;
 182
 183 typedef enum
 184 {
 185   NNFW_TRAIN_OPTIMIZER_SGD = 0,
 186   NNFW_TRAIN_OPTIMIZER_ADAM = 1,
 187 } NNFW_TRAIN_OPTIMIZER;
 188
 189 /**
 190  * @brief Training information to prepare training
 191  * @todo  Add more training information
 192  *        (e.g. optimizer, loss function, ...)
 193  */
 194 typedef struct nnfw_train_info
 195 {
 196   /** Learning rate */
 197   float learning_rate = 0.001f;
 198   /** Batch size */
 199   uint32_t batch_size = 1;
 200   /** loss type */
 201   NNFW_TRAIN_LOSS loss = NNFW_TRAIN_LOSS_MEAN_SQUARED_ERROR;
 202   /** optimizer type */
 203   NNFW_TRAIN_OPTIMIZER opt = NNFW_TRAIN_OPTIMIZER_SGD;
 204 } nnfw_train_info;
 205
 206 /**
 207  * @brief Prepare session to be ready for training
 208  * @note  The session will be entered into training mode
 209  *
 210  * @param[in] session The session to be prepared for training
 211  * @param[in] info    Training information.
 212  *                    If info is nullptr, it will not change training information.
 213  *                    If it is nullptr and model has not training information,
 214  *                    it will use default training information.
 215  *                    Default training information is {learning_rate = 0.001f, batch_size = 1}
 216  *
 217  * @return  @c NNFW_STATUS_NO_ERROR if successful
 218  */
 219 NNFW_STATUS nnfw_train_prepare(nnfw_session *session, const nnfw_train_info *info);
 220
 221 /**
 222  * @brief Set training input
 223  * @note  This function should be called after {@link nnfw_train_prepare}
 224  *
 225  * @param[in] session     The session to be set training inputs and expected model outputs
 226  * @param[in] index       The index of training input
 227  * @param[in] input       The input buffers for training
 228  * @param[in] input_info  The shape and type of input buffer
 229  *                        If it is nullptr, it will not change shape and batch size
 230  * @return  @c NNFW_STATUS_NO_ERROR if successful
 231  */
 232 NNFW_STATUS nnfw_train_set_input(nnfw_session *session, uint32_t index, const void *input,
 233                                  const nnfw_tensorinfo *input_info);
 234
 235 /**
 236  * @brief Set training expected output
 237  * @note  This function should be called after {@link nnfw_train_prepare}
 238  *
 239  * @param session       The session to be set training inputs and expected model outputs
 240  * @param index         The index of training expected output
 241  * @param expected      The expected buffers for training
 242  * @param expected_info The shape and type of expected buffer
 243  *                      If it is nullptr, it will not change shape and batch size
 244  * @return  @c NNFW_STATUS_NO_ERROR if successful
 245  */
 246 NNFW_STATUS nnfw_train_set_expected(nnfw_session *session, uint32_t index, const void *expected,
 247                                     const nnfw_tensorinfo *expected_info);
 248
 249 /**
 250  * @brief Train the model
 251  * @note  This function should be called after {@link nnfw_train_set_input} and
 252  *        {@link nnfw_train_set_expected} for each input and expected output
 253  *
 254  * @param[in] session The session to be trained
 255  * @param[in] update_weights If true, update weights of the model
 256  *                           If false, do not update weights of the model (for validation)
 257  * @return  @c NNFW_STATUS_NO_ERROR if successful
 258  */
 259 NNFW_STATUS nnfw_train(nnfw_session *session, bool update_weights);
 260
 261 /**
 262  * @brief Get loss value for expected output
 263  * @note  This function should be called after {@link nnfw_train}
 264  *
 265  * @param[in]   session The session to get loss value
 266  * @param[in]   index   The index of loss value [0, number of expected outputs)
 267  * @param[out]  loss    The loss value
 268  * @return  @c NNFW_STATUS_NO_ERROR if successful
 269  */
 270 NNFW_STATUS nnfw_train_get_loss(nnfw_session *session, uint32_t index, float *loss);
 271
 272 /**
 273  * @brief Export circle model
 274  * @note  This function should be called on training mode
 275  *        This function should be called after {@link nnfw_train}
 276  *
 277  * @param[in] session The session to export inference model
 278  * @param[in] path    The path to export inference model
 279  * @return @c NNFW_STATUS_NO_ERROR if successful
 280  */
 281 NNFW_STATUS nnfw_train_export_circle(nnfw_session *session, const char *path);
 282
 283 //////////////////////////////////////////////
 284 // Optional APIs for training
 285 //////////////////////////////////////////////
 286
 287 /**
 288  * @brief Get the training model input information
 289  * @note  This function should be called after {@link nnfw_train_prepare}
 290  *
 291  * @param[in]   session The session to get the training model input information
 292  * @param[in]   index   The index of training model input
 293  * @param[out]  info    The shape and type of training model input
 294  * @return @c NNFW_STATUS_NO_ERROR if successful
 295  */
 296 NNFW_STATUS nnfw_train_input_tensorinfo(nnfw_session *session, uint32_t index,
 297                                         nnfw_tensorinfo *info);
 298
 299 /**
 300  * @brief Get the training model expected output information
 301  * @note  This function should be called after {@link nnfw_train_prepare}
 302  *
 303  * @param[in]   session The session to get the training model expected output information
 304  * @param[in]   index   The index of training model expected output
 305  * @param[out]  info    The shape and type of training model expected output
 306  * @return @c NNFW_STATUS_NO_ERROR if successful
 307  */
 308 NNFW_STATUS nnfw_train_expected_tensorinfo(nnfw_session *session, uint32_t index,
 309                                            nnfw_tensorinfo *info);
 310
 311 //////////////////////////////////////////////
 312 // Not planned to be implemented
 313 //////////////////////////////////////////////
 314
 315 /**
 316  * @brief Convert between training mode and inference mode
 317  * @note  This function should be called after {@link nnfw_train} or {@link nnfw_prepare}
 318  *
 319  * @param[in] session The session to convert training mode to inference mode
 320  * @param[in] train   If false, convert training model to inference model
 321  *                    If true, convert inference model to training model
 322  * @return  @c NNFW_STATUS_NO_ERROR if successful
 323  */
 324 // NNFW_STATUS nnfw_set_training_mode(nnfw_session *session, bool train);
 325
 326 /**
 327  * @brief Set training information after prepare training
 328  * @note  This function may be used after {@link nnfw_train_prepare}
 329  *
 330  * @param[in] session The session prepared for training
 331  * @param[in] info    Training information
 332  * @return  @c NNFW_STATUS_NO_ERROR if successful
 333  */
 334 // NNFW_STATUS nnfw_train_set_traininfo(nnfw_session *session, const nnfw_train_info info);
 335
 336 /**
 337  *  On-Device Quantization APIs
 338  *
 339  * On-Device Quantization APIs are designed to be used in the following order
 340  * 1. nnfw_set_quantization_type
 341  * 2. nnfw_set_quantized_model_path
 342  * 3. nnfw_quantize
 343  *
 344  * You should use Quantization APIs after {@link nnfw_load_model_from_file},
 345  * before {@link nnfw_prepare} and {@link nnfw_set_input_tensorinfo}.
 346  */
 347
 348 /**
 349  * @brief quantization type
 350  */
 351 typedef enum
 352 {
 353   /** default value: type not set */
 354   NNFW_QUANTIZE_TYPE_NOT_SET,
 355   /** asymmetric quantization with a scale and zero point */
 356   NNFW_QUANTIZE_TYPE_U8_ASYM,
 357   /** symmetric quantization with a scale only */
 358   NNFW_QUANTIZE_TYPE_I16_SYM,
 359 } NNFW_QUANTIZE_TYPE;
 360
 361 /**
 362  * @brief Set quantization type
 363  *
 364  * This function should be called before {@link nnfw_quantize} is invoked.
 365  *
 366  * @param[in] session nnfw_session to set quantization type
 367  * @param[in] pref @c NNFW_QUANTIZE_TYPE
 368  * @return    @c NNFW_STATUS_NO_ERROR if successful,
 369  *            @c NNFW_STATUS_UNEXPECTED_NULL if session is null,
 370  *            otherwise return @c NNFW_STATUS_ERROR
 371  */
 372 NNFW_STATUS nnfw_set_quantization_type(nnfw_session *session, NNFW_QUANTIZE_TYPE qtype);
 373
 374 /**
 375  * @brief Set exported quantized model path
 376  *
 377  * This function should be called before {@link nnfw_quantize} is invoked.
 378  *
 379  * TODO: If this function is not called, quantized model will not be exported
 380  *
 381  * @param[in] session nnfw_session to set quantized model path
 382  * @param[in] path    Quantized model path
 383  * @return    @c NNFW_STATUS_NO_ERROR if successful, otherwise return @c NNFW_STATUS_ERROR
 384  */
 385 NNFW_STATUS nnfw_set_quantized_model_path(nnfw_session *session, const char *path);
 386
 387 /**
 388  * @brief Quantize circle model
 389  *
 390  * @param[in] session nnfw_session to quantize
 391  * @return    @c ODC_STATUS_NO_ERROR if successful, otherwise return @c ODC_STATUS_ERROR
 392  */
 393 NNFW_STATUS nnfw_quantize(nnfw_session *session);
 394
 395 #ifdef __cplusplus
 396 }
 397 #endif
 398
 399 #endif // __NNFW_EXPERIMENTAL_H__