|
Nux C API
0.0.1
C API of NPU Engine
|
#include <stdarg.h>#include <stdbool.h>#include <stdint.h>#include <stdlib.h>Go to the source code of this file.
Macros | |
| #define | profiler_resource_t_CPU (uint32_t)1 |
| #define | profiler_resource_t_NPU (uint32_t)2 |
Typedefs | |
| typedef enum Axis | Axis |
| typedef enum TensorDataType | TensorDataType |
| Represent tensor data type. More... | |
| typedef enum nux_error_t | nux_error_t |
| Represent a return status of a function that can fail. More... | |
| typedef enum nux_log_level_t | nux_log_level_t |
| typedef enum profiler_format_t | profiler_format_t |
| typedef struct BlockingSession | BlockingSession |
| typedef struct CompletionQueue_ContextPtr | CompletionQueue_ContextPtr |
| typedef struct Model | Model |
| typedef struct Nux | Nux |
| typedef struct NuxModel | NuxModel |
| typedef struct OpaqueTensor | OpaqueTensor |
| typedef struct ProfilerGuard | ProfilerGuard |
| typedef struct SessionOptions | SessionOptions |
| typedef struct Submitter_ContextPtr | Submitter_ContextPtr |
| typedef struct Task | Task |
| typedef struct TaskModel | TaskModel |
| typedef struct TensorArray | TensorArray |
| typedef struct TensorDesc | TensorDesc |
| typedef struct Nux * | nux_handle_t |
| Nux handle. More... | |
| typedef uintptr_t | nux_buffer_len_t |
| Byte length of a data buffer. More... | |
| typedef struct Model * | nux_sync_model_t |
| Handle of a synchronous model. More... | |
| typedef struct OpaqueTensor * | nux_tensor_t |
| Handle of tensor. More... | |
| typedef uint8_t * | nux_buffer_t |
| Pointer to a data buffer. More... | |
| typedef uintptr_t | RequestId |
| typedef RequestId | nux_request_id_t |
| Identifier to distinguish tasks in a task model. More... | |
| typedef uint32_t | OutputIndex |
| typedef OutputIndex | nux_output_index_t |
| Index of an output tensor, used in task model. More... | |
| typedef void(* | nux_output_callback_t) (nux_request_id_t, nux_output_index_t, nux_buffer_t, nux_buffer_len_t) |
| Callback function called per tensor output when a task of a task model is completed. More... | |
| typedef void(* | nux_error_callback_t) (nux_request_id_t, enum nux_error_t) |
| Callback function called when a task fails to complete. More... | |
| typedef void(* | nux_finish_callback_t) (nux_request_id_t) |
| Callback function which is finally called when a task is completed. More... | |
| typedef struct TaskModel * | nux_task_model_t |
| Handle of a task model. More... | |
| typedef struct Task * | nux_task_t |
| Handle of a task of a task model. More... | |
| typedef uint32_t | InputIndex |
| typedef InputIndex | nux_input_index_t |
| Index of an input tensor, used in task model. More... | |
| typedef struct SessionOptions * | nux_session_option_t |
| Session option. More... | |
| typedef const struct BlockingSession * | nux_session_t |
| Session. More... | |
| typedef const struct NuxModel * | nux_model_t |
| Model. More... | |
| typedef struct TensorArray * | nux_tensor_array_t |
| typedef struct Submitter_ContextPtr * | nux_async_session_t |
| Async Session. More... | |
| typedef struct CompletionQueue_ContextPtr * | nux_completion_queue_t |
| typedef void * | nux_context_t |
| Context pointer. More... | |
| typedef const struct TensorDesc * | nux_tensor_desc_t |
| typedef char * | nux_string_t |
| A null-terminated C string. More... | |
| typedef enum TensorDataType | nux_tensor_dtype_t |
| Represent a data type of tensor. More... | |
| typedef uint32_t | profiler_resource_t |
| typedef struct ProfilerGuard * | profiler_handle_t |
| typedef Span * | profiler_span_t |
| typedef const Config * | npu_config_t |
Functions | |
| const char * | version (void) |
| Return a version of Nux native library. More... | |
| const char * | git_short_hash (void) |
| Return a short Git hash of Nux native library. More... | |
| const char * | build_timestamp (void) |
| Return a build timestamp of Nux native library. More... | |
| void | enable_logging (enum nux_log_level_t _log_level) |
| Enable a logger with a specific log level. More... | |
| void | register_signal_handler (void) |
| Register Ctrl-C signal handler to exit process. More... | |
| enum nux_error_t | create_nux (nux_handle_t *nux) |
| Creates a new nux handle. More... | |
| void | destroy_nux (nux_handle_t nux) |
| Destroy the Nux handle and release its resources. More... | |
| enum nux_error_t | nux_create_sync_model (nux_handle_t nux, const uint8_t *buffer, nux_buffer_len_t len, nux_sync_model_t *model) |
| Create an instance of a synchronous model. More... | |
| void | destroy_sync_model (nux_sync_model_t model) |
| Destroy the sync model and release its resources. More... | |
| uint32_t | model_count_inputs (nux_sync_model_t model) |
| Return the number of input tensors of a given sync model. More... | |
| uint32_t | model_count_outputs (nux_sync_model_t model) |
| Return the number of output tensors of a given sync model. More... | |
| enum nux_error_t | model_input_tensor (nux_sync_model_t model, uint32_t index, nux_tensor_t *tensor) |
| Get the handle of a specified input tensor from a given sync model. More... | |
| enum nux_error_t | model_output_tensor (nux_sync_model_t model, uint32_t index, nux_tensor_t *tensor) |
| Get the handle of a specified output tensor from a given sync model. More... | |
| enum nux_error_t | model_run (nux_sync_model_t model) |
| Run a single inference task. More... | |
| enum nux_error_t | tensor_get_buffer (nux_tensor_t tensor, nux_buffer_t *buffer, nux_buffer_len_t *len) |
| Get a pointer to the data buffer of a given tensor. More... | |
| enum nux_error_t | tensor_fill_buffer (nux_tensor_t tensor, nux_buffer_t buffer, nux_buffer_len_t len) |
| Copy data into the data buffer of a specified input tensor. More... | |
| enum nux_error_t | tensor_set_buffer (nux_tensor_t tensor, nux_buffer_t buffer, nux_buffer_len_t len, void(*free)(uint8_t *, uintptr_t)) |
| Specify a pointer to a data buffer to a specified input tensor. More... | |
| enum nux_error_t | nux_create_task_model (nux_handle_t nux, const uint8_t *buffer, nux_buffer_len_t len, uint32_t max_batch, nux_output_callback_t output_callback, nux_error_callback_t error_callback, nux_finish_callback_t finish_callback, nux_task_model_t *task_model) |
| Create an instance of a task model. More... | |
| void | destroy_task_model (nux_task_model_t task_model) |
| Destroy the task model and release its resources. More... | |
| bool | task_model_is_all_task_done (nux_task_model_t task_model) |
Return true if there's no running tasks, or false if any task is still running. More... | |
| enum nux_error_t | task_model_get_task (nux_task_model_t task_model, nux_task_t *task) |
| Get a task handle from a specified task model. More... | |
| enum nux_error_t | task_model_try_get_task (nux_task_model_t task_model, nux_task_t *task) |
| (non-blocking) Get a task handle from the specified task model. More... | |
| void | destroy_task (nux_task_t task) |
| Destroy the task and release its resources. More... | |
| enum nux_error_t | task_execute (nux_task_t task, nux_request_id_t request_id) |
| Request one asynchronous inference task. More... | |
| nux_buffer_t | task_input (nux_task_t task, nux_input_index_t index) |
| Return a mutable pointer to the buffer of the specified input tensor. More... | |
| nux_buffer_len_t | task_input_size (nux_task_t task, nux_input_index_t index) |
| Return the buffer length in bytes of the specified input tensor. More... | |
| nux_session_option_t | nux_session_option_create (void) |
| Create a session option. More... | |
| void | nux_session_option_set_device (nux_session_option_t builder, const char *devname) |
| Set a NPU device to the given session option. More... | |
| void | nux_session_option_set_worker_num (nux_session_option_t builder, uintptr_t num) |
| Set the number of workers to the given session option. More... | |
| void | nux_session_option_set_batch_size (nux_session_option_t builder, uintptr_t num) |
| Set the batch size of input tensors. More... | |
| void | nux_session_option_set_compiler_log_path (nux_session_option_t builder, const char *path) |
| Set the file path to which the compiler saves log messages. More... | |
| void | nux_session_option_enable_compiler_hints (nux_session_option_t builder, bool enable) |
| Enable the compiler hints. More... | |
| void | nux_session_option_set_input_queue_size (nux_session_option_t builder, uintptr_t len) |
| Set the input queue size of async session. More... | |
| void | nux_session_option_set_output_queue_size (nux_session_option_t builder, uintptr_t len) |
| Set the output queue size of async session. More... | |
| enum nux_error_t | nux_session_option_set_compiler_config (nux_session_option_t option, const char *yaml) |
| Set a compiler config to the given session option. More... | |
| void | nux_session_option_destroy (nux_session_option_t option) |
| Destroy a session option. More... | |
| enum nux_error_t | nux_session_create (nux_buffer_t model_binary, nux_buffer_len_t model_binary_len, nux_session_option_t option, nux_session_t *out_sess) |
| Create a session. More... | |
| nux_model_t | nux_session_get_model (nux_session_t sess) |
| Get the pointer of the Model of a given session. More... | |
| enum nux_error_t | nux_session_run (nux_session_t sess, nux_tensor_array_t inputs, nux_tensor_array_t outputs) |
| Run an inference task. More... | |
| enum nux_error_t | nux_session_run_with (nux_session_t sess, const char *const *input_names, uintptr_t input_len, const char *const *output_names, uintptr_t output_len, nux_tensor_array_t inputs, nux_tensor_array_t outputs) |
| Run an inference task with tensor names The number of input/output tensors and its corresponding names must be the same. More... | |
| void | nux_session_destroy (nux_session_t sess) |
| Destroy a session. More... | |
| enum nux_error_t | nux_async_session_create (nux_buffer_t model_binary, nux_buffer_len_t model_binary_len, nux_session_option_t option, nux_async_session_t *out_sess, nux_completion_queue_t *out_queue) |
| Create an asynchronous session and a queue to receive the results. More... | |
| enum nux_error_t | nux_async_session_run (nux_async_session_t sess, nux_context_t context, nux_tensor_array_t inputs) |
| Submit an inference task asynchronously. It returns immediately. More... | |
| bool | nux_completion_queue_next (nux_completion_queue_t queue, nux_context_t *context, nux_tensor_array_t *outputs, enum nux_error_t *error) |
| Wait until it receives any completion event, which can be success or fail. More... | |
| bool | nux_completion_queue_try_next (nux_completion_queue_t queue, nux_context_t *context, nux_tensor_array_t *outputs, enum nux_error_t *error) |
It's almost the same as nux_completion_queue_next. However, this call immediately returns even if it hasn't received any result event after the last call. In the case, it will set error to nux_error_t_queue_no_data. More... | |
| bool | nux_completion_queue_next_timeout (nux_completion_queue_t queue, uint64_t timeout_ms, nux_context_t *context, nux_tensor_array_t *outputs, enum nux_error_t *error) |
It's almost the same as nux_completion_queue_next. However, this call will be blocked only until a timeout occurs even if it hasn't received any result. In this case, it will set nux_error_t_queue_wait_timeout to error. More... | |
| nux_model_t | nux_async_session_get_model (nux_async_session_t sess) |
| Get the pointer of the Model of a given asynchronous session. More... | |
| void | nux_async_session_destroy (nux_async_session_t sess) |
| Destroy an asynchronous session. More... | |
| void | nux_completion_queue_destroy (nux_completion_queue_t queue) |
| Destroy a completion queue. More... | |
| uintptr_t | nux_input_num (nux_model_t model) |
| Return the number of input tensors of the given model. More... | |
| uintptr_t | nux_output_num (nux_model_t model) |
| Return the number of output tensors of the given model. More... | |
| nux_tensor_desc_t | nux_tensor_desc_by_name (nux_model_t model, const char *name) |
| Return the description of the tensor matched to the given name. More... | |
| nux_tensor_desc_t | nux_input_desc (nux_model_t model, uintptr_t index) |
| Return the description of i-th input tensor of the given model. More... | |
| nux_tensor_desc_t | nux_output_desc (nux_model_t model, uintptr_t index) |
| Return the description of i-th output tensor of the given model. More... | |
| nux_string_t | nux_tensor_name (nux_tensor_desc_t tensor) |
| Return the tensor name and transfers its ownership to the caller. To destroy nux_string_t, please call nux_string_destroy. More... | |
| uintptr_t | nux_tensor_dim_num (nux_tensor_desc_t tensor) |
| Return the number of dimensions of the given tensor. More... | |
| uintptr_t | nux_tensor_dim (nux_tensor_desc_t tensor, uintptr_t index) |
| Return the dimension size of the dimension index. More... | |
| uintptr_t | nux_tensor_stride (nux_tensor_desc_t tensor, uintptr_t index) |
| Return the stride value of the dimension index. More... | |
| enum Axis | nux_tensor_axis (nux_tensor_desc_t tensor, uintptr_t idx) |
| Return the axis type of i-th dimension (e.g., Width, Height, Channel) More... | |
| nux_tensor_dtype_t | nux_tensor_dtype (nux_tensor_desc_t tensor) |
| Return the tensor data type. More... | |
| enum nux_error_t | nux_tensor_quantization_parameter (nux_tensor_desc_t tensor, double *scale, int32_t *zero_point) |
| Return the quantization parameter. More... | |
| uintptr_t | nux_tensor_len (nux_tensor_desc_t tensor) |
| Return the total number of all elements. More... | |
| uintptr_t | nux_tensor_size (nux_tensor_desc_t tensor) |
| Return the byte size of tensor. More... | |
| nux_tensor_t | nux_tensor_create (nux_tensor_desc_t desc) |
| Create a tensor according to a given tensor description. More... | |
| nux_tensor_t | nux_tensor_create_with_buffer (nux_tensor_desc_t desc, nux_buffer_t buffer, nux_buffer_len_t len, void(*free)(uint8_t *, uintptr_t)) |
| Create a tensor with an exiting buffer. It doesn't copy the data. More... | |
| void | nux_tensor_destroy (nux_tensor_t tensor) |
| Destroy a tensor. More... | |
| uint8_t * | nux_tensor_buffer (nux_tensor_t tensor) |
| Return the pointer to the buffer of this tensor. More... | |
| uintptr_t | nux_tensor_buffer_size (nux_tensor_t tensor) |
| Return the size of tensor buffer. More... | |
| nux_tensor_array_t | nux_tensor_array_allocate_by_names (nux_model_t model, const char *const *names, uintptr_t len) |
| Return an array of tensors corresponding to the names with allocated buffers. More... | |
| nux_tensor_array_t | nux_tensor_array_create_by_names (nux_model_t model, const char *const *names, uintptr_t len) |
| Return an array of tensors corresponding to the names without allocated buffers. More... | |
| nux_tensor_array_t | nux_tensor_array_allocate_inputs (nux_model_t model) |
| Return an array of input tensors with allocated buffers. More... | |
| nux_tensor_array_t | nux_tensor_array_create_inputs (nux_model_t model) |
| Return an array of input tensors without allocated buffers. More... | |
| nux_tensor_array_t | nux_tensor_array_allocate_outputs (nux_model_t model) |
| Return an array of output tensors with allocated buffers. More... | |
| nux_tensor_array_t | nux_tensor_array_create_outputs (nux_model_t model) |
| Return an array of output tensors without allocated buffers. More... | |
| nux_tensor_t | nux_tensor_array_get (nux_tensor_array_t array, uintptr_t index) |
| Return a tensor from the given tensor array. More... | |
| uintptr_t | nux_tensor_array_len (nux_tensor_array_t array) |
| Return the number of tensors in the given tensor array. More... | |
| void | nux_tensor_array_destroy (nux_tensor_array_t array) |
| Destroy a tensor array. More... | |
| void | nux_buffer_destroy (uint8_t *buf, nux_buffer_len_t len) |
| Destroy a buffer. More... | |
| void | nux_string_destroy (nux_string_t str) |
| Destroy a buffer. More... | |
| enum nux_error_t | profiler_enable (profiler_resource_t resource, enum profiler_format_t format, const char *config, profiler_handle_t *profiler) |
| Enable a profiler and return the profiler handle. More... | |
| void | profiler_disable (profiler_handle_t profiler) |
| Disable a profiler. More... | |
| profiler_span_t | profiler_record_start (const char *record_name, bool _warm_up) |
| Create beginning profiler span with specified name. More... | |
| void | profiler_record_end (profiler_span_t span) |
| Create end profiler span with specified name. More... | |
| npu_config_t | get_npu_spec (const char *npuid) |
| Get NPU specification by NPUID. More... | |
| #define profiler_resource_t_CPU (uint32_t)1 |
| #define profiler_resource_t_NPU (uint32_t)2 |
| typedef struct BlockingSession BlockingSession |
| typedef struct CompletionQueue_ContextPtr CompletionQueue_ContextPtr |
| typedef uint32_t InputIndex |
| typedef const Config* npu_config_t |
| typedef struct Submitter_ContextPtr* nux_async_session_t |
Async Session.
| typedef uintptr_t nux_buffer_len_t |
Byte length of a data buffer.
| typedef uint8_t* nux_buffer_t |
Pointer to a data buffer.
In Nux, it is commonly used to contain any kind of binary data like ENF binary, or a data buffer of input/output tensors.
| typedef struct CompletionQueue_ContextPtr* nux_completion_queue_t |
| typedef void* nux_context_t |
Context pointer.
| typedef void(* nux_error_callback_t) (nux_request_id_t, enum nux_error_t) |
Callback function called when a task fails to complete.
| typedef enum nux_error_t nux_error_t |
Represent a return status of a function that can fail.
| typedef void(* nux_finish_callback_t) (nux_request_id_t) |
Callback function which is finally called when a task is completed.
Unlike nux_output_callback_t, this callback function is called only once after nux_output_callback_t is called for all output tensors.
| typedef struct Nux* nux_handle_t |
Nux handle.
create_nux initializes an instance of nux_handle_t.
| typedef InputIndex nux_input_index_t |
Index of an input tensor, used in task model.
| typedef enum nux_log_level_t nux_log_level_t |
| typedef const struct NuxModel* nux_model_t |
Model.
| typedef void(* nux_output_callback_t) (nux_request_id_t, nux_output_index_t, nux_buffer_t, nux_buffer_len_t) |
Callback function called per tensor output when a task of a task model is completed.
For example, if one model has 2 output tensors, this function will be called 2 times upon each task's completion.
| typedef OutputIndex nux_output_index_t |
Index of an output tensor, used in task model.
| typedef RequestId nux_request_id_t |
Identifier to distinguish tasks in a task model.
| typedef struct SessionOptions* nux_session_option_t |
Session option.
| typedef const struct BlockingSession* nux_session_t |
Session.
| typedef char* nux_string_t |
A null-terminated C string.
| typedef struct Model* nux_sync_model_t |
Handle of a synchronous model.
nux_create_sync_model initializes an instance of nux_sync_model_t.
| typedef struct TaskModel* nux_task_model_t |
Handle of a task model.
nux_create_task_model creates an instance of nux_task_model_t.
| typedef struct Task* nux_task_t |
Handle of a task of a task model.
task_model_get_task or task_model_try_get_task returns an instance of nux_task_t.
| typedef struct TensorArray* nux_tensor_array_t |
| typedef const struct TensorDesc* nux_tensor_desc_t |
| typedef enum TensorDataType nux_tensor_dtype_t |
Represent a data type of tensor.
| typedef struct OpaqueTensor* nux_tensor_t |
Handle of tensor.
model_input_tensor or model_output_tensor returns an instance of nux_tensor_t.
| typedef struct OpaqueTensor OpaqueTensor |
| typedef uint32_t OutputIndex |
| typedef enum profiler_format_t profiler_format_t |
| typedef struct ProfilerGuard* profiler_handle_t |
| typedef uint32_t profiler_resource_t |
| typedef Span* profiler_span_t |
| typedef struct ProfilerGuard ProfilerGuard |
| typedef uintptr_t RequestId |
| typedef struct SessionOptions SessionOptions |
| typedef struct Submitter_ContextPtr Submitter_ContextPtr |
| typedef struct TensorArray TensorArray |
| typedef enum TensorDataType TensorDataType |
Represent tensor data type.
| typedef struct TensorDesc TensorDesc |
| enum Axis |
| enum nux_error_t |
Represent a return status of a function that can fail.
| Enumerator | |
|---|---|
| nux_error_t_success | When a function call is successful |
| nux_error_t_nux_creation_failed | When create_nux fails to initialize |
| nux_error_t_model_deploy_failed | When deploying a model to an executor fails. See also nux_create_sync_model, nux_create_task_model for more details. |
| nux_error_t_model_execution_failed | When running an inference task fails. See also model_run, task_execute for more details. |
| nux_error_t_invalid_input_index | When the given index of an input tensor is invalid. See also model_input_tensor for more details. |
| nux_error_t_invalid_output_index | When the given index of an output tensor is invalid. See also model_output_tensor for more details. |
| nux_error_t_invalid_buffer | When a data buffer is invalid. See tensor_set_buffer for more details. |
| nux_error_t_invalid_inputs | When the input tensors are invalid |
| nux_error_t_invalid_outputs | When the output tensors are invalid |
| nux_error_t_get_task_failed | When task_model_get_task or task_model_try_get_task fails to return an available task slot. This error code can have different meanings in both functions. Please see task_model_get_task and task_model_try_get_task for more details. |
| nux_error_t_dump_profile_failed | reserved |
| nux_error_t_queue_wait_timeout | When waiting for completion queue is timed out |
| nux_error_t_queue_no_data | When there's no data in completion queue |
| nux_error_t_incompatible_model | When loading a model image fails |
| nux_error_t_compilation_failed | When the compiler fails to transform a given model image to a binary for NPU |
| nux_error_t_internal_error | Internal error |
| nux_error_t_invalid_yaml | Invalid yaml syntax |
| nux_error_t_incompatible_api_client_error | incompatible api client error |
| nux_error_t_api_client_init_failed | when api client fails to initialize |
| nux_error_t_no_api_key | No API Key |
| nux_error_t_null_pointer_exception | Null pointer exception |
| nux_error_t_invalid_session_options | Invalid session option |
| nux_error_t_session_terminated | Session termination |
| nux_error_t_device_busy | NPU device is busy |
| nux_error_t_tensor_name_not_found | Tensor name not found in a given model |
| nux_error_t_unsupported_feature | Unsupported feature |
| nux_error_t_npu_interrupt | Npu interrupt |
| nux_error_t_npu_error | Npu error, TODO, specify all errors in here |
| nux_error_t_queue_full | When a queue is full |
| nux_error_t_queue_empty | When a queue is empty |
| nux_error_t_invalid_compiler_config | When a compiler config is invalid |
| enum nux_log_level_t |
| enum profiler_format_t |
| enum TensorDataType |
Represent tensor data type.
| const char* build_timestamp | ( | void | ) |
Return a build timestamp of Nux native library.
| enum nux_error_t create_nux | ( | nux_handle_t * | nux | ) |
Creates a new nux handle.
| [out] | nux | Mutable pointer to receive a created Nux handle |
| void destroy_nux | ( | nux_handle_t | nux | ) |
Destroy the Nux handle and release its resources.
| nux | Nux handle to be destroyed. It must not be NULL. |
| void destroy_sync_model | ( | nux_sync_model_t | model | ) |
Destroy the sync model and release its resources.
| model | Sync model to be destroyed, and it must not be NULL. |
| void destroy_task | ( | nux_task_t | task | ) |
Destroy the task and release its resources.
task, the task will get destroyed automatically. Please do not call destroy_task with the task which is already passed to task_execute.| task | Task to be destroyed |
| void destroy_task_model | ( | nux_task_model_t | task_model | ) |
Destroy the task model and release its resources.
| task_model | Task model to be destroyed |
| void enable_logging | ( | enum nux_log_level_t | _log_level | ) |
Enable a logger with a specific log level.
| log_level | Log level (off, error, warn, info) |
| npu_config_t get_npu_spec | ( | const char * | npuid | ) |
Get NPU specification by NPUID.
| npuid | NPUID, indicating a specific NPU configuration with a certain NPU chip. Currently, available NPUIDs are WARBOY and WARBOY-2PE. |
| const char* git_short_hash | ( | void | ) |
Return a short Git hash of Nux native library.
| uint32_t model_count_inputs | ( | nux_sync_model_t | model | ) |
Return the number of input tensors of a given sync model.
A model can have more than one input tensor. This function returns how many input tensors this model has.
| model | Sync model |
| uint32_t model_count_outputs | ( | nux_sync_model_t | model | ) |
Return the number of output tensors of a given sync model.
A model can have more than one output tensor. This function returns how many output tensors this model has.
| model | Sync model |
| enum nux_error_t model_input_tensor | ( | nux_sync_model_t | model, |
| uint32_t | index, | ||
| nux_tensor_t * | tensor | ||
| ) |
Get the handle of a specified input tensor from a given sync model.
model is called.| model | Sync model | |
| index | Input tensor index | |
| [out] | tensor | Mutable pointer to receive the handle of a specified input tensor |
| enum nux_error_t model_output_tensor | ( | nux_sync_model_t | model, |
| uint32_t | index, | ||
| nux_tensor_t * | tensor | ||
| ) |
Get the handle of a specified output tensor from a given sync model.
model is called.| model | Sync model | |
| index | Output tensor index | |
| [out] | tensor | Mutable pointer to receive a specified output tensor handle |
| enum nux_error_t model_run | ( | nux_sync_model_t | model | ) |
Run a single inference task.
Before calling this function, you must fill input tensors with proper data. Please refer to model_input_tensor and tensor_set_buffer to learn how to fill input tensors with data.
| enum nux_error_t nux_async_session_create | ( | nux_buffer_t | model_binary, |
| nux_buffer_len_t | model_binary_len, | ||
| nux_session_option_t | option, | ||
| nux_async_session_t * | out_sess, | ||
| nux_completion_queue_t * | out_queue | ||
| ) |
Create an asynchronous session and a queue to receive the results.
nux_async_session_t allows users to submit inference tasks. nux_completion_queue_t is an iterator to receive the result in the asynchronous way. See also nux_async_session_run and nux_completion_queue_next.
| model_binary | Buffer which contains a model binary | |
| model_binary_len | Length of model_binary | |
| option | Session option. If it is null, the default option will be used. | |
| [out] | out_sess | Mutable pointer to an instance of async session |
| [out] | out_queue | Mutable pointer to an instance of async completion queue |
| void nux_async_session_destroy | ( | nux_async_session_t | sess | ) |
Destroy an asynchronous session.
| nux_model_t nux_async_session_get_model | ( | nux_async_session_t | sess | ) |
Get the pointer of the Model of a given asynchronous session.
| sess | Handle of asynchronous session instance. It must not be NULL. |
| enum nux_error_t nux_async_session_run | ( | nux_async_session_t | sess, |
| nux_context_t | context, | ||
| nux_tensor_array_t | inputs | ||
| ) |
Submit an inference task asynchronously. It returns immediately.
You can receive the completed inference results through nux_completion_queue_t. please refer to nux_completion_queue_next to know how to receive the completed results.
| sess | Handle of asynchronous session |
| <tt>context</tt> | is a void pointer, so you can pass any data to context. Generally, context can be used to identify what's the completion event. Also, sophisticated data structure can be used to to do more as soon as you receive the completion event. You must make sure the pointer must be valid as long as you want to use a passed context even after you receive the completion event. |
| inputs | an array of tensors |
| void nux_buffer_destroy | ( | uint8_t * | buf, |
| nux_buffer_len_t | len | ||
| ) |
Destroy a buffer.
| buffer | Byte buffer to be destroyed. It must not be NULL. |
| len | Byte length of buffer |
| void nux_completion_queue_destroy | ( | nux_completion_queue_t | queue | ) |
Destroy a completion queue.
| bool nux_completion_queue_next | ( | nux_completion_queue_t | queue, |
| nux_context_t * | context, | ||
| nux_tensor_array_t * | outputs, | ||
| enum nux_error_t * | error | ||
| ) |
Wait until it receives any completion event, which can be success or fail.
| queue | Async completion queue | |
| [out] | context | A pointer of the context value that you passed to nux_async_session_run |
| [out] | outputs | Output tensors |
| [out] | error | nux_error_t_success if successful, nux_error_t_session_terminated if the async session is terminated, or it will return other error value. |
| bool nux_completion_queue_next_timeout | ( | nux_completion_queue_t | queue, |
| uint64_t | timeout_ms, | ||
| nux_context_t * | context, | ||
| nux_tensor_array_t * | outputs, | ||
| enum nux_error_t * | error | ||
| ) |
It's almost the same as nux_completion_queue_next. However, this call will be blocked only until a timeout occurs even if it hasn't received any result. In this case, it will set nux_error_t_queue_wait_timeout to error.
| queue | Async completion queue | |
| timeout_ms | How long to wait before giving up, and its time unit is milliseconds. | |
| [out] | context | A pointer of the context value that you passed to nux_async_session_run |
| [out] | outputs | Output tensors |
| [out] | error | nux_error_t_success if successful, nux_error_t_session_terminated if the async session is terminated, #queue_wait_timeout if no data is received until the timeout, or it will return other error value. |
| bool nux_completion_queue_try_next | ( | nux_completion_queue_t | queue, |
| nux_context_t * | context, | ||
| nux_tensor_array_t * | outputs, | ||
| enum nux_error_t * | error | ||
| ) |
It's almost the same as nux_completion_queue_next. However, this call immediately returns even if it hasn't received any result event after the last call. In the case, it will set error to nux_error_t_queue_no_data.
| queue | Async completion queue | |
| [out] | context | A pointer of the context value that you passed to nux_async_session_run |
| [out] | outputs | Output tensors |
| [out] | error | nux_error_t_success if successful, nux_error_t_session_terminated if the async session is terminated, nux_error_t_queue_no_data if no result is received, or it will return other error value. |
| enum nux_error_t nux_create_sync_model | ( | nux_handle_t | nux, |
| const uint8_t * | buffer, | ||
| nux_buffer_len_t | len, | ||
| nux_sync_model_t * | model | ||
| ) |
Create an instance of a synchronous model.
It creates a synchronous model to execute a compiled ENF binary. The synchronous model provides APIs to run a single inference task with one input batch at a time.
| nux | Nux handle | |
| buffer | Byte buffer containing ENF binary | |
| len | Byte length of buffer | |
| [out] | model | Mutable pointer to receive the handle of a created sync model |
| enum nux_error_t nux_create_task_model | ( | nux_handle_t | nux, |
| const uint8_t * | buffer, | ||
| nux_buffer_len_t | len, | ||
| uint32_t | max_batch, | ||
| nux_output_callback_t | output_callback, | ||
| nux_error_callback_t | error_callback, | ||
| nux_finish_callback_t | finish_callback, | ||
| nux_task_model_t * | task_model | ||
| ) |
Create an instance of a task model.
It allows users to run multiple inference tasks asynchronously and simultaneously. When each task is completed or failed, corresponding callback functions will be called with nux_request_id_t, an identifier of a task request. See also task_execute for more details.
| nux | Nux handle |
| buffer | Byte buffer containing ENF binary |
| len | Byte length of buffer |
| max_batch | Number of concurrent running tasks It can be limited according to internal configurations and HW capacity. |
| output_callback | Callback function invoked when a task is completed. It will be called per output tensor. Please see nux_output_callback_t for more details. |
| error_callback | Callback function invoked when a task is failed. |
| finish_callback | Callback function which will be called finally after the output_callback is called after all output tensors. |
| task_model | Mutable pointer to receive the handle of a created task model |
| nux_tensor_desc_t nux_input_desc | ( | nux_model_t | model, |
| uintptr_t | index | ||
| ) |
Return the description of i-th input tensor of the given model.
| uintptr_t nux_input_num | ( | nux_model_t | model | ) |
Return the number of input tensors of the given model.
| nux_tensor_desc_t nux_output_desc | ( | nux_model_t | model, |
| uintptr_t | index | ||
| ) |
Return the description of i-th output tensor of the given model.
| uintptr_t nux_output_num | ( | nux_model_t | model | ) |
Return the number of output tensors of the given model.
| enum nux_error_t nux_session_create | ( | nux_buffer_t | model_binary, |
| nux_buffer_len_t | model_binary_len, | ||
| nux_session_option_t | option, | ||
| nux_session_t * | out_sess | ||
| ) |
Create a session.
Session provides simple and synchronous APIs to run inference tasks from a loaded model.
| model_binary | Buffer which contains a model binary | |
| model_binary_len | Length of model_binary | |
| option | Session option. If it is null, the default option will be used. | |
| [out] | sess | Mutable pointer to receive a created Nux handle |
| void nux_session_destroy | ( | nux_session_t | sess | ) |
Destroy a session.
| sess | Handle of Session instance to be destroyed. It must not be NULL. |
| nux_model_t nux_session_get_model | ( | nux_session_t | sess | ) |
Get the pointer of the Model of a given session.
| sess | Handle of session instance. It must not be NULL. |
| nux_session_option_t nux_session_option_create | ( | void | ) |
Create a session option.
It allows to specify more options for a session.
| void nux_session_option_destroy | ( | nux_session_option_t | option | ) |
Destroy a session option.
| void nux_session_option_enable_compiler_hints | ( | nux_session_option_t | builder, |
| bool | enable | ||
| ) |
Enable the compiler hints.
The compilation step prints out the hints of model performances as warning logs if True.
| option | Session option |
| path | Log path |
| void nux_session_option_set_batch_size | ( | nux_session_option_t | builder, |
| uintptr_t | num | ||
| ) |
Set the batch size of input tensors.
The batch size allows to add the dimension of input tensors to feed each inference.
| option | Session option |
| num | Batch size |
| enum nux_error_t nux_session_option_set_compiler_config | ( | nux_session_option_t | option, |
| const char * | yaml | ||
| ) |
Set a compiler config to the given session option.
If compiler config is not set, Session will use a default compiler config.
| option | Session option |
| yaml | A yaml formatted string of compiler option |
yaml is not a valid yaml document. | void nux_session_option_set_compiler_log_path | ( | nux_session_option_t | builder, |
| const char * | path | ||
| ) |
Set the file path to which the compiler saves log messages.
| option | Session option |
| path | Log path |
| void nux_session_option_set_device | ( | nux_session_option_t | builder, |
| const char * | devname | ||
| ) |
Set a NPU device to the given session option.
If NPU device is not set, Session will use the default NPU device npu0pe0.
| option | Session option |
| devname | A NPU device name (e.g., npu0pe0, npu1pe0) |
| void nux_session_option_set_input_queue_size | ( | nux_session_option_t | builder, |
| uintptr_t | len | ||
| ) |
Set the input queue size of async session.
async session has both input and output queues. The input queue keeps inference requests until the async session handles them. If it is not set, async session will have the unlimited input queue size by default. An unlimited input queue will keep the requests as much as your system's memory allow.
When a input queue length is specified and the queue is full, the caller of async session will be blocked until async session digests the requests. It's useful especially when you want backpressure.
| option | Session option |
| num | The input queue size, and it must be > 0 and < 2^31. |
| void nux_session_option_set_output_queue_size | ( | nux_session_option_t | builder, |
| uintptr_t | len | ||
| ) |
Set the output queue size of async session.
async session has both input and output queues. The output queue keeps inference results until the consumer drains the results. If it is not set, async session will have the unlimited output queue size by default. An unlimited output queue will keep the responses as much as your system's memory allow.
When a output queue length is specified and the queue is full, async session will be blocked until consumers drain the results. It's useful especially when you want to prevent the out of memory issue.
| option | Session option |
| num | The output queue size, and it must be be > 0 and < 2^31. |
| void nux_session_option_set_worker_num | ( | nux_session_option_t | builder, |
| uintptr_t | num | ||
| ) |
Set the number of workers to the given session option.
The number of workers means how many workers handle the inference requests. By default, the number of workers is 1.
| option | Session option |
| num | The number of workers, and it must be a positive integer. |
| enum nux_error_t nux_session_run | ( | nux_session_t | sess, |
| nux_tensor_array_t | inputs, | ||
| nux_tensor_array_t | outputs | ||
| ) |
Run an inference task.
| sess | Handle of Session instance. It must not be NULL. |
| inputs | Input tensors |
| outputs | Output tensors |
| enum nux_error_t nux_session_run_with | ( | nux_session_t | sess, |
| const char *const * | input_names, | ||
| uintptr_t | input_len, | ||
| const char *const * | output_names, | ||
| uintptr_t | output_len, | ||
| nux_tensor_array_t | inputs, | ||
| nux_tensor_array_t | outputs | ||
| ) |
Run an inference task with tensor names The number of input/output tensors and its corresponding names must be the same.
| sess | Handle of Session instance. It must not be NULL. |
| input_names | An array of input tensor names |
| input_len | Number of input tensor names |
| output_names | An array of output tensor names |
| output_len | Number of output tensor names |
| inputs | Input tensors |
| outputs | Output tensors |
| void nux_string_destroy | ( | nux_string_t | str | ) |
Destroy a buffer.
| buffer | Byte buffer to be destroyed. It must not be NULL. |
| len | Byte length of buffer |
| nux_tensor_array_t nux_tensor_array_allocate_by_names | ( | nux_model_t | model, |
| const char *const * | names, | ||
| uintptr_t | len | ||
| ) |
Return an array of tensors corresponding to the names with allocated buffers.
| nux_tensor_array_t nux_tensor_array_allocate_inputs | ( | nux_model_t | model | ) |
Return an array of input tensors with allocated buffers.
This function is generally used with tensor_fill_buffer.
| nux_tensor_array_t nux_tensor_array_allocate_outputs | ( | nux_model_t | model | ) |
Return an array of output tensors with allocated buffers.
| nux_tensor_array_t nux_tensor_array_create_by_names | ( | nux_model_t | model, |
| const char *const * | names, | ||
| uintptr_t | len | ||
| ) |
Return an array of tensors corresponding to the names without allocated buffers.
| nux_tensor_array_t nux_tensor_array_create_inputs | ( | nux_model_t | model | ) |
Return an array of input tensors without allocated buffers.
This function is generally used with tensor_set_buffer.
| nux_tensor_array_t nux_tensor_array_create_outputs | ( | nux_model_t | model | ) |
Return an array of output tensors without allocated buffers.
| void nux_tensor_array_destroy | ( | nux_tensor_array_t | array | ) |
Destroy a tensor array.
| nux_tensor_t nux_tensor_array_get | ( | nux_tensor_array_t | array, |
| uintptr_t | index | ||
| ) |
Return a tensor from the given tensor array.
| uintptr_t nux_tensor_array_len | ( | nux_tensor_array_t | array | ) |
Return the number of tensors in the given tensor array.
| enum Axis nux_tensor_axis | ( | nux_tensor_desc_t | tensor, |
| uintptr_t | idx | ||
| ) |
Return the axis type of i-th dimension (e.g., Width, Height, Channel)
| uint8_t* nux_tensor_buffer | ( | nux_tensor_t | tensor | ) |
Return the pointer to the buffer of this tensor.
| uintptr_t nux_tensor_buffer_size | ( | nux_tensor_t | tensor | ) |
Return the size of tensor buffer.
| nux_tensor_t nux_tensor_create | ( | nux_tensor_desc_t | desc | ) |
Create a tensor according to a given tensor description.
You have to call nux_tensor_destroy to release the resource of a create tensor.
| nux_tensor_t nux_tensor_create_with_buffer | ( | nux_tensor_desc_t | desc, |
| nux_buffer_t | buffer, | ||
| nux_buffer_len_t | len, | ||
| void(*)(uint8_t *, uintptr_t) | free | ||
| ) |
Create a tensor with an exiting buffer. It doesn't copy the data.
| nux_tensor_desc_t nux_tensor_desc_by_name | ( | nux_model_t | model, |
| const char * | name | ||
| ) |
Return the description of the tensor matched to the given name.
| void nux_tensor_destroy | ( | nux_tensor_t | tensor | ) |
Destroy a tensor.
| uintptr_t nux_tensor_dim | ( | nux_tensor_desc_t | tensor, |
| uintptr_t | index | ||
| ) |
Return the dimension size of the dimension index.
| uintptr_t nux_tensor_dim_num | ( | nux_tensor_desc_t | tensor | ) |
Return the number of dimensions of the given tensor.
| nux_tensor_dtype_t nux_tensor_dtype | ( | nux_tensor_desc_t | tensor | ) |
Return the tensor data type.
| uintptr_t nux_tensor_len | ( | nux_tensor_desc_t | tensor | ) |
Return the total number of all elements.
| nux_string_t nux_tensor_name | ( | nux_tensor_desc_t | tensor | ) |
Return the tensor name and transfers its ownership to the caller. To destroy nux_string_t, please call nux_string_destroy.
| Tensor | descriptor |
| enum nux_error_t nux_tensor_quantization_parameter | ( | nux_tensor_desc_t | tensor, |
| double * | scale, | ||
| int32_t * | zero_point | ||
| ) |
Return the quantization parameter.
Currently only supports per-tensor quantized case.
| uintptr_t nux_tensor_size | ( | nux_tensor_desc_t | tensor | ) |
Return the byte size of tensor.
It will be useful when you have to fill the tensor buffer with data.
| uintptr_t nux_tensor_stride | ( | nux_tensor_desc_t | tensor, |
| uintptr_t | index | ||
| ) |
Return the stride value of the dimension index.
| void profiler_disable | ( | profiler_handle_t | profiler | ) |
Disable a profiler.
| profiler | A profiler handle to be disabled. |
| enum nux_error_t profiler_enable | ( | profiler_resource_t | resource, |
| enum profiler_format_t | format, | ||
| const char * | config, | ||
| profiler_handle_t * | profiler | ||
| ) |
Enable a profiler and return the profiler handle.
| resource | Target resource to be profiled. e.g. CPU or NPU. | |
| format | Profiler format. e.g. ChromeTrace. | |
| config | Format specific config. You need to pass valid arguments for the format. | |
| [out] | profiler | A profiler handle. |
config is not a valid yaml document. | void profiler_record_end | ( | profiler_span_t | span | ) |
Create end profiler span with specified name.
| A | span handle. |
| profiler_span_t profiler_record_start | ( | const char * | record_name, |
| bool | _warm_up | ||
| ) |
Create beginning profiler span with specified name.
| record_name | Profiler record span name. |
| warm_up | If true, do not record profiler result, and just warm up. |
| void register_signal_handler | ( | void | ) |
Register Ctrl-C signal handler to exit process.
| enum nux_error_t task_execute | ( | nux_task_t | task, |
| nux_request_id_t | request_id | ||
| ) |
Request one asynchronous inference task.
task_execute submits a request for an inference task identified by task. Once a task is completed, output_callback function passed to nux_create_task_model will be called with a distinct output index per output tensor. finish_callback function will be also called after output_callback function is called for all output tensors.
task, the task will get destroyed automatically. Please do not call destroy_task with the task which is already passed to task_execute.| task | Task handle obtained from calling task_model_get_task or task_model_try_get_task. |
| request_id | An positive integer to distinguish task requests. The behavior of task_execute doesn't rely on a request_id value at all. request_id will be just passed to callback functions. |
| nux_buffer_t task_input | ( | nux_task_t | task, |
| nux_input_index_t | index | ||
| ) |
Return a mutable pointer to the buffer of the specified input tensor.
| task | Task handle |
| index | Index of the input tensor |
| nux_buffer_len_t task_input_size | ( | nux_task_t | task, |
| nux_input_index_t | index | ||
| ) |
Return the buffer length in bytes of the specified input tensor.
| task | Task handle |
| index | Index of the input tensor |
| enum nux_error_t task_model_get_task | ( | nux_task_model_t | task_model, |
| nux_task_t * | task | ||
| ) |
Get a task handle from a specified task model.
When there's no available task in a given task model, it will block until new task is available.
| task_model | Handle of a task model | |
| [out] | task | Mutable pointer to receive the handle of a created task |
| bool task_model_is_all_task_done | ( | nux_task_model_t | task_model | ) |
Return true if there's no running tasks, or false if any task is still running.
| task_model | Task handle |
| enum nux_error_t task_model_try_get_task | ( | nux_task_model_t | task_model, |
| nux_task_t * | task | ||
| ) |
(non-blocking) Get a task handle from the specified task model.
It's the non-blocking version of task_model_get_task. This function returns an available task, or it will return immediately nux_error_t_get_task_failed if there's no available task in a given task model.
| task_model | Handle of a task model | |
| [out] | task | Mutable pointer to receive the handle of a created task |
| enum nux_error_t tensor_fill_buffer | ( | nux_tensor_t | tensor, |
| nux_buffer_t | buffer, | ||
| nux_buffer_len_t | len | ||
| ) |
Copy data into the data buffer of a specified input tensor.
To execute model_run, you first need to fill input tensors with data. tensor_fill_buffer copies the data into the data buffer of a specified input tensor.
| tensor | Tensor handle into which you want to copy input data |
| buffer | Pointer to the data buffer |
| len | Byte length of buffer |
buffer is invalid. | enum nux_error_t tensor_get_buffer | ( | nux_tensor_t | tensor, |
| nux_buffer_t * | buffer, | ||
| nux_buffer_len_t * | len | ||
| ) |
Get a pointer to the data buffer of a given tensor.
Once model_run is called, the inference result will be written into output tensors. This function returns a pointer to the data buffer of a specified output tensor.
| tensor | Tensor from which you want to get a pointer of the data buffer | |
| [out] | buffer | Mutable pointer to receive the pointer to the data buffer |
| [out] | len | Byte length of buffer |
| enum nux_error_t tensor_set_buffer | ( | nux_tensor_t | tensor, |
| nux_buffer_t | buffer, | ||
| nux_buffer_len_t | len, | ||
| void(*)(uint8_t *, uintptr_t) | free | ||
| ) |
Specify a pointer to a data buffer to a specified input tensor.
This function is almost same to tensor_fill_buffer. However, tensor takes the ownership of the buffer with free function to deallocate the buffer. Ensure that nothing else uses the pointer after calling this function.
if free is null, tensor will not deallocate the buffer. It can be useful when you want to reuse the buffer or buffer is on a stack area of a function. Please ensure that the buffer must be deallocated manually by users in order to prevent the memory leak.
| tensor | Tensor handle into which you want to copy input data |
| buffer | Pointer to the data buffer |
| len | Byte length of buffer |
| free | a function pointer to deallocate a buffer. If free is null, tensor will not deallocate the data. |
buffer is invalid. | const char* version | ( | void | ) |
Return a version of Nux native library.
1.9.1