2 * Copyright (c) 2019 Samsung Electronics Co., Ltd. All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef __NNFW_EXPERIMENTAL_H__
18 #define __NNFW_EXPERIMENTAL_H__
26 // Used for custom kernel development
29 * operand type, used only for custom operations
38 * Used as input to custom operation eval function
46 nnfw_operand *outputs;
47 } nnfw_custom_kernel_params;
50 * Custom kernel evaluation function
52 * param[in] params custom operation parameters
53 * param[in] userdata pointer to user-specified buffer( kernel instance specific )
55 typedef void (*nnfw_custom_eval)(nnfw_custom_kernel_params *params, char *userdata,
56 size_t userdata_size);
59 * custom operation registration info
63 nnfw_custom_eval eval_function;
64 } custom_kernel_registration_info;
66 NNFW_STATUS nnfw_register_custom_op_info(nnfw_session *session, const char *id,
67 custom_kernel_registration_info *info);
70 * @brief Get the input tensor index by name
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 .
76 * @note If two or more input tensors are of the same name, the one with the lowest index is always
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
84 NNFW_STATUS nnfw_input_tensorindex(nnfw_session *session, const char *tensorname, uint32_t *index);
87 * @brief Get the input tensor index by name
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 .
93 * @note If two or more input tensors are of the same name, the one with the lowest index is always
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
101 NNFW_STATUS nnfw_output_tensorindex(nnfw_session *session, const char *tensorname, uint32_t *index);
104 * @brief Set the backend for each operation in the session
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.
110 * @note The argument specifying backends must be in the format
111 * "OP_BACKEND_MAP=\"0=acl_cl;1=cpu;2=acl_cl\"".
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
117 NNFW_STATUS nnfw_set_backends_per_operation(nnfw_session *session, const char *backend_settings);
120 * Prepare session to be ready for inference
121 * This phase may finalize model compilation, scheduling, and additional settings.
123 * @param session the session to be prepared
124 * @return NNFW_STATUS_NO_ERROR if successful
126 NNFW_STATUS nnfw_prepare_pipeline(nnfw_session *session, const char *map_file_path = nullptr);
129 * @brief Set input buffer
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.
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
141 * @return @c NNFW_STATUS_NO_ERROR if successful
143 NNFW_STATUS nnfw_push_pipeline_input(nnfw_session *session, void *inputs, void *lengths);
146 * @brief Get last outputs of partitioned model in session
148 * This function must be called after {@link nnfw_prepare_pipeline}, \p outputs given to this
149 * function must be cleared for memory management.
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
155 * @return @c NNFW_STATUS_NO_ERROR if successful
157 NNFW_STATUS nnfw_pop_pipeline_output(nnfw_session *session, void *outputs);
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
166 * 4. nnfw_train_get_loss
168 * If you want to inference after training with the same session, you can use the following order
174 //////////////////////////////////////////////
175 // Essential APIs for training
176 //////////////////////////////////////////////
179 NNFW_TRAIN_LOSS_MEAN_SQUARED_ERROR = 0,
180 NNFW_TRAIN_LOSS_CATEGORICAL_CROSSENTROPY = 1,
185 NNFW_TRAIN_OPTIMIZER_SGD = 0,
186 NNFW_TRAIN_OPTIMIZER_ADAM = 1,
187 } NNFW_TRAIN_OPTIMIZER;
190 * @brief Training information to prepare training
191 * @todo Add more training information
192 * (e.g. optimizer, loss function, ...)
194 typedef struct nnfw_train_info
197 float learning_rate = 0.001f;
199 uint32_t batch_size = 1;
201 NNFW_TRAIN_LOSS loss = NNFW_TRAIN_LOSS_MEAN_SQUARED_ERROR;
202 /** optimizer type */
203 NNFW_TRAIN_OPTIMIZER opt = NNFW_TRAIN_OPTIMIZER_SGD;
207 * @brief Prepare session to be ready for training
208 * @note The session will be entered into training mode
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}
217 * @return @c NNFW_STATUS_NO_ERROR if successful
219 NNFW_STATUS nnfw_train_prepare(nnfw_session *session, const nnfw_train_info *info);
222 * @brief Set training input
223 * @note This function should be called after {@link nnfw_train_prepare}
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
232 NNFW_STATUS nnfw_train_set_input(nnfw_session *session, uint32_t index, const void *input,
233 const nnfw_tensorinfo *input_info);
236 * @brief Set training expected output
237 * @note This function should be called after {@link nnfw_train_prepare}
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
246 NNFW_STATUS nnfw_train_set_expected(nnfw_session *session, uint32_t index, const void *expected,
247 const nnfw_tensorinfo *expected_info);
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
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
259 NNFW_STATUS nnfw_train(nnfw_session *session, bool update_weights);
262 * @brief Get loss value for expected output
263 * @note This function should be called after {@link nnfw_train}
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
270 NNFW_STATUS nnfw_train_get_loss(nnfw_session *session, uint32_t index, float *loss);
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}
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
281 NNFW_STATUS nnfw_train_export_circle(nnfw_session *session, const char *path);
283 //////////////////////////////////////////////
284 // Optional APIs for training
285 //////////////////////////////////////////////
288 * @brief Get the training model input information
289 * @note This function should be called after {@link nnfw_train_prepare}
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
296 NNFW_STATUS nnfw_train_input_tensorinfo(nnfw_session *session, uint32_t index,
297 nnfw_tensorinfo *info);
300 * @brief Get the training model expected output information
301 * @note This function should be called after {@link nnfw_train_prepare}
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
308 NNFW_STATUS nnfw_train_expected_tensorinfo(nnfw_session *session, uint32_t index,
309 nnfw_tensorinfo *info);
311 //////////////////////////////////////////////
312 // Not planned to be implemented
313 //////////////////////////////////////////////
316 * @brief Convert between training mode and inference mode
317 * @note This function should be called after {@link nnfw_train} or {@link nnfw_prepare}
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
324 // NNFW_STATUS nnfw_set_training_mode(nnfw_session *session, bool train);
327 * @brief Set training information after prepare training
328 * @note This function may be used after {@link nnfw_train_prepare}
330 * @param[in] session The session prepared for training
331 * @param[in] info Training information
332 * @return @c NNFW_STATUS_NO_ERROR if successful
334 // NNFW_STATUS nnfw_train_set_traininfo(nnfw_session *session, const nnfw_train_info info);
337 * On-Device Quantization APIs
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
344 * You should use Quantization APIs after {@link nnfw_load_model_from_file},
345 * before {@link nnfw_prepare} and {@link nnfw_set_input_tensorinfo}.
349 * @brief quantization type
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;
362 * @brief Set quantization type
364 * This function should be called before {@link nnfw_quantize} is invoked.
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
372 NNFW_STATUS nnfw_set_quantization_type(nnfw_session *session, NNFW_QUANTIZE_TYPE qtype);
375 * @brief Set exported quantized model path
377 * This function should be called before {@link nnfw_quantize} is invoked.
379 * TODO: If this function is not called, quantized model will not be exported
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
385 NNFW_STATUS nnfw_set_quantized_model_path(nnfw_session *session, const char *path);
388 * @brief Quantize circle model
390 * @param[in] session nnfw_session to quantize
391 * @return @c ODC_STATUS_NO_ERROR if successful, otherwise return @c ODC_STATUS_ERROR
393 NNFW_STATUS nnfw_quantize(nnfw_session *session);
399 #endif // __NNFW_EXPERIMENTAL_H__