From 2b6f102f22dc78ba2126a7e91468626e004f7ce3 Mon Sep 17 00:00:00 2001 From: Yongjoo Ahn Date: Thu, 21 Sep 2023 13:13:18 +0900 Subject: [PATCH] [header] Add ml-api-experimental.h header file - Add the header file consists of experimental APIs which would be included as regular APIs in future releases. Signed-off-by: Yongjoo Ahn --- c/include/meson.build | 1 + c/include/ml-api-experimental.h | 178 ++++++++++++++++++++++++++ c/include/nnstreamer-tizen-internal.h | 154 ---------------------- c/meson.build | 4 + c/src/ml-api-common.c | 1 + c/src/ml-api-service-private.h | 1 + packaging/machine-learning-api.spec | 11 ++ tests/capi/unittest_capi_inference.cc | 1 + 8 files changed, 197 insertions(+), 154 deletions(-) create mode 100644 c/include/ml-api-experimental.h diff --git a/c/include/meson.build b/c/include/meson.build index 4a5f5afd..c42c7d58 100644 --- a/c/include/meson.build +++ b/c/include/meson.build @@ -7,3 +7,4 @@ else endif nns_capi_service_headers = files('ml-api-service.h') +nns_capi_experimental_headers = files('ml-api-experimental.h') diff --git a/c/include/ml-api-experimental.h b/c/include/ml-api-experimental.h new file mode 100644 index 00000000..0f2e8b8c --- /dev/null +++ b/c/include/ml-api-experimental.h @@ -0,0 +1,178 @@ +/* SPDX-License-Identifier: Apache-2.0 */ +/** + * Copyright (c) 2023 Samsung Electronics Co., Ltd. All Rights Reserved. + * + * @file ml-api-experimental.h + * @date 21 September 2023 + * @brief ML-API Header for Experimental Features. APIs here would be included as regular features in future releases. + * @author Yongjoo Ahn + * @bug No known bugs except for NYI items + */ + +#ifndef __ML_API_EXPERIMENTAL_H__ +#define __ML_API_EXPERIMENTAL_H__ + +#include +#include +#include +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/** + * @brief Gets the version number of machine-learning API. (major.minor.micro) + * @since_tizen 8.0 + * @param[out] major The pointer to store the major version number. Set null if won't fetch the version. + * @param[out] minor The pointer to store the minor version number. Set null if won't fetch the version. + * @param[out] micro The pointer to store the micro version number. Set null if won't fetch the version. + */ +void ml_api_get_version (unsigned int *major, unsigned int *minor, unsigned int *micro); + +/** + * @brief Gets the version string of machine-learning API. + * @since_tizen 8.0 + * @return Newly allocated string. The returned string should be freed with free(). + */ +char * ml_api_get_version_string (void); + + +typedef enum { + ML_SERVICE_TYPE_UNKNOWN = 0, + ML_SERVICE_TYPE_SERVER_PIPELINE, + ML_SERVICE_TYPE_CLIENT_QUERY, + ML_SERVICE_TYPE_REMOTE, + + ML_SERVICE_TYPE_MAX +} ml_service_type_e; + +typedef enum { + ML_REMOTE_SERVICE_TYPE_UNKNOWN = 0, + ML_REMOTE_SERVICE_TYPE_MODEL_RAW, + ML_REMOTE_SERVICE_TYPE_MODEL_URI, + ML_REMOTE_SERVICE_TYPE_PIPELINE_RAW, + ML_REMOTE_SERVICE_TYPE_PIPELINE_URI, + + ML_REMOTE_SERVICE_TYPE_MAX +} ml_remote_service_type_e; + + +/** + * @brief Creates ml remote service handle with given ml-option handle. + * @since_tizen 8.0 + * @note This is not official and public API but experimental API. + * @details The caller should set one of "remote_sender" and "remote_receiver" as a service type in @a ml_option. + * @remarks The @a handle should be destroyed using ml_service_destroy(). + * @param[in] option The option used for creating query service. + * @param[out] handle Newly created query service handle is returned. + * @return @c 0 on Success. Otherwise a negative error value. + * @retval #ML_ERROR_NONE Successful. + * @retval #ML_ERROR_NOT_SUPPORTED Not supported. + * @retval #ML_ERROR_INVALID_PARAMETER Fail. The parameter is invalid. + * @retval #ML_ERROR_OUT_OF_MEMORY Failed to allocate required memory. + * @retval #ML_ERROR_STREAMS_PIPE Failed to launch the pipeline. + * @retval #ML_ERROR_TRY_AGAIN The pipeline is not ready yet. + */ +int ml_remote_service_create (ml_option_h option, ml_service_h *handle); + +/** + * @todo DRAFT. API name should be determined later. + * @brief Register new information, such as neural network models or pipeline descriptions, on a remote server. + * @since_tizen 8.0 + * @note This is not official and public API but experimental API. + * @param[in] handle The query service handle created by ml_service_query_create(). + * @param[in] option The option used for registering machine learning service. + * @param[in] data The Data to be registered on the remote server. + * @return 0 on success. Otherwise a negative error value. + * @retval #ML_ERROR_NONE Successful. + * @retval #ML_ERROR_NOT_SUPPORTED Not supported. + * @retval #ML_ERROR_INVALID_PARAMETER Given parameter is invalid. + * + * Here is an example of the usage: + * @code + * // ================== Client side ================== + * // Example of saving a model file received from a client. + * + * + * status = ml_option_create (&client_option_h); + * + * gchar *client_node_type = g_strdup ("remote_sender"); + * status = ml_option_set (client_option_h, "node-type", client_node_type, g_free); + * + * gchar *client_connect_type = g_strdup ("TCP"); + * ml_option_set (client_option_h, "connect-type", client_connect_type, g_free); + * + * status = ml_remote_service_create (client_option_h, &client_h); + * + * // ================== Server side ================== + * ml_service_h server_h; + * ml_option_h server_option_h = NULL; + * + * // Set option to handle + * ml_option_create (&server_option_h); + * + * gchar *server_node_type = g_strdup ("remote_receiver"); + * ml_option_set (server_option_h, "node-type", server_node_type, g_free); + * + * gchar *server_connect_type = g_strdup ("TCP"); + * ml_option_set (server_option_h, "connect-type", server_connect_type, g_free); + * + * // Create ml-remote service. + * ml_remote_service_create (server_option_h, &server_h) + * + * // ================== Client side ================== + * // Send neural network model url to the query server. + * ml_service_h client_h; + * ml_option_h client_option_h = NULL; + * + * // Set option to handle + * ml_option_create (&client_option_h); + * + * gchar *node_type = g_strdup ("remote_launch_client"); + * ml_option_set (client_option_h, "node_type", node_type, g_free); + * + * // Set the options required for connection, such as server address, port, protocol, etc. + * gchar *dest_host = g_strdup ("localhost"); + * ml_option_set (client_option_h, "dest_host", dest_host, g_free); + * + * // Create query service. + * ml_remote_service_create (client_option_h, &client_h); + * + * ml_option_h query_option_h = NULL; + * ml_option_create (&query_option_h); + * + * // ================== Create service option ================== + * // Load model files. + * ml_option_h remote_service_option_h = NULL; + * ml_option_create (&remote_service_option_h); + * + * gchar *service_key = g_strdup ("model_registration_test_key"); + * ml_option_set (remote_service_option_h, "service-key", service_key, g_free); + * + * gchar *service_type = g_strdup ("model_raw"); + * ml_option_set (remote_service_option_h, "service-type", service_type, g_free); + * + * gchar *activate = g_strdup ("true"); + * ml_option_set (remote_service_option_h, "activate", activate, g_free); + * + * gchar *description = g_strdup ("temp description for remote model register test"); + * ml_option_set (remote_service_option_h, "description", description, g_free); + * + * gchar *name = g_strdup ("model_name.nnfw"); + * ml_option_set (remote_service_option_h, "name", name, g_free); + * + * ml_remote_service_register (client_h, remote_service_option_h, contents, len); + * + * ml_service_destroy (client_h); + * ml_service_destroy (server_h); + * ml_option_destroy (server_option_h); + * ml_option_destroy (client_option_h); + * ml_option_destroy (remote_service_option_h); + * + * @endcode + */ +int ml_remote_service_register (ml_service_h handle, ml_option_h option, void *data, size_t data_len); + +#ifdef __cplusplus +} +#endif /* __cplusplus */ +#endif /* __ML_API_EXPERIMENTAL_H__ */ diff --git a/c/include/nnstreamer-tizen-internal.h b/c/include/nnstreamer-tizen-internal.h index 6e9a6d2d..5cdc1391 100644 --- a/c/include/nnstreamer-tizen-internal.h +++ b/c/include/nnstreamer-tizen-internal.h @@ -14,7 +14,6 @@ #include #include -#include #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ @@ -45,159 +44,6 @@ typedef struct { */ int ml_single_open_custom (ml_single_h *single, ml_single_preset *info); -/** - * @brief Gets the version number of machine-learning API. (major.minor.micro) - * @since_tizen 8.0 - * @param[out] major The pointer to store the major version number. Set null if won't fetch the version. - * @param[out] minor The pointer to store the minor version number. Set null if won't fetch the version. - * @param[out] micro The pointer to store the micro version number. Set null if won't fetch the version. - */ -void ml_api_get_version (unsigned int *major, unsigned int *minor, unsigned int *micro); - -/** - * @brief Gets the version string of machine-learning API. - * @since_tizen 8.0 - * @return Newly allocated string. The returned string should be freed with free(). - */ -char * ml_api_get_version_string (void); - - -typedef enum { - ML_SERVICE_TYPE_UNKNOWN = 0, - ML_SERVICE_TYPE_SERVER_PIPELINE, - ML_SERVICE_TYPE_CLIENT_QUERY, - ML_SERVICE_TYPE_REMOTE, - - ML_SERVICE_TYPE_MAX -} ml_service_type_e; - -typedef enum { - ML_REMOTE_SERVICE_TYPE_UNKNOWN = 0, - ML_REMOTE_SERVICE_TYPE_MODEL_RAW, - ML_REMOTE_SERVICE_TYPE_MODEL_URI, - ML_REMOTE_SERVICE_TYPE_PIPELINE_RAW, - ML_REMOTE_SERVICE_TYPE_PIPELINE_URI, - - ML_REMOTE_SERVICE_TYPE_MAX -} ml_remote_service_type_e; - - -/** - * @brief Creates ml remote service handle with given ml-option handle. - * @since_tizen 8.0 - * @note This is not official and public API but experimental API. - * @details The caller should set one of "remote_sender" and "remote_receiver" as a service type in @a ml_option. - * @remarks The @a handle should be destroyed using ml_service_destroy(). - * @param[in] option The option used for creating query service. - * @param[out] handle Newly created query service handle is returned. - * @return @c 0 on Success. Otherwise a negative error value. - * @retval #ML_ERROR_NONE Successful. - * @retval #ML_ERROR_NOT_SUPPORTED Not supported. - * @retval #ML_ERROR_INVALID_PARAMETER Fail. The parameter is invalid. - * @retval #ML_ERROR_OUT_OF_MEMORY Failed to allocate required memory. - * @retval #ML_ERROR_STREAMS_PIPE Failed to launch the pipeline. - * @retval #ML_ERROR_TRY_AGAIN The pipeline is not ready yet. - */ -int ml_remote_service_create (ml_option_h option, ml_service_h *handle); - -/** - * @todo DRAFT. API name should be determined later. - * @brief Register new information, such as neural network models or pipeline descriptions, on a remote server. - * @since_tizen 8.0 - * @note This is not official and public API but experimental API. - * @param[in] handle The query service handle created by ml_service_query_create(). - * @param[in] option The option used for registering machine learning service. - * @param[in] data The Data to be registered on the remote server. - * @return 0 on success. Otherwise a negative error value. - * @retval #ML_ERROR_NONE Successful. - * @retval #ML_ERROR_NOT_SUPPORTED Not supported. - * @retval #ML_ERROR_INVALID_PARAMETER Given parameter is invalid. - * - * Here is an example of the usage: - * @code - * // ================== Client side ================== - * // Example of saving a model file received from a client. - * - * - * status = ml_option_create (&client_option_h); - * - * gchar *client_node_type = g_strdup ("remote_sender"); - * status = ml_option_set (client_option_h, "node-type", client_node_type, g_free); - * - * gchar *client_connect_type = g_strdup ("TCP"); - * ml_option_set (client_option_h, "connect-type", client_connect_type, g_free); - * - * status = ml_remote_service_create (client_option_h, &client_h); - * - * // ================== Server side ================== - * ml_service_h server_h; - * ml_option_h server_option_h = NULL; - * - * // Set option to handle - * ml_option_create (&server_option_h); - * - * gchar *server_node_type = g_strdup ("remote_receiver"); - * ml_option_set (server_option_h, "node-type", server_node_type, g_free); - * - * gchar *server_connect_type = g_strdup ("TCP"); - * ml_option_set (server_option_h, "connect-type", server_connect_type, g_free); - * - * // Create ml-remote service. - * ml_remote_service_create (server_option_h, &server_h) - * - * // ================== Client side ================== - * // Send neural network model url to the query server. - * ml_service_h client_h; - * ml_option_h client_option_h = NULL; - * - * // Set option to handle - * ml_option_create (&client_option_h); - * - * gchar *node_type = g_strdup ("remote_launch_client"); - * ml_option_set (client_option_h, "node_type", node_type, g_free); - * - * // Set the options required for connection, such as server address, port, protocol, etc. - * gchar *dest_host = g_strdup ("localhost"); - * ml_option_set (client_option_h, "dest_host", dest_host, g_free); - * - * // Create query service. - * ml_remote_service_create (client_option_h, &client_h); - * - * ml_option_h query_option_h = NULL; - * ml_option_create (&query_option_h); - * - * // ================== Create service option ================== - * // Load model files. - * ml_option_h remote_service_option_h = NULL; - * ml_option_create (&remote_service_option_h); - * - * gchar *service_key = g_strdup ("model_registration_test_key"); - * ml_option_set (remote_service_option_h, "service-key", service_key, g_free); - * - * gchar *service_type = g_strdup ("model_raw"); - * ml_option_set (remote_service_option_h, "service-type", service_type, g_free); - * - * gchar *activate = g_strdup ("true"); - * ml_option_set (remote_service_option_h, "activate", activate, g_free); - * - * gchar *description = g_strdup ("temp description for remote model register test"); - * ml_option_set (remote_service_option_h, "description", description, g_free); - * - * gchar *name = g_strdup ("model_name.nnfw"); - * ml_option_set (remote_service_option_h, "name", name, g_free); - * - * ml_remote_service_register (client_h, remote_service_option_h, contents, len); - * - * ml_service_destroy (client_h); - * ml_service_destroy (server_h); - * ml_option_destroy (server_option_h); - * ml_option_destroy (client_option_h); - * ml_option_destroy (remote_service_option_h); - * - * @endcode - */ -int ml_remote_service_register (ml_service_h handle, ml_option_h option, void *data, size_t data_len); - #ifdef __cplusplus } #endif /* __cplusplus */ diff --git a/c/meson.build b/c/meson.build index c247e492..69881ab7 100644 --- a/c/meson.build +++ b/c/meson.build @@ -84,4 +84,8 @@ if get_option('enable-ml-service') install_headers(nns_capi_service_headers, subdir: 'nnstreamer' ) + + install_headers(nns_capi_experimental_headers, + subdir: 'nnstreamer' + ) endif diff --git a/c/src/ml-api-common.c b/c/src/ml-api-common.c index 970df23a..a7bf97a3 100644 --- a/c/src/ml-api-common.c +++ b/c/src/ml-api-common.c @@ -18,6 +18,7 @@ #include "nnstreamer.h" #include "nnstreamer-tizen-internal.h" #include "ml-api-internal.h" +#include "ml-api-experimental.h" /** * @brief Enumeration for ml_info type. diff --git a/c/src/ml-api-service-private.h b/c/src/ml-api-service-private.h index 1c4ce406..b7931cd9 100644 --- a/c/src/ml-api-service-private.h +++ b/c/src/ml-api-service-private.h @@ -22,6 +22,7 @@ #include "resource-dbus.h" #include "nnstreamer-edge.h" #include "nnstreamer-tizen-internal.h" +#include "ml-api-experimental.h" #ifdef __cplusplus extern "C" { diff --git a/packaging/machine-learning-api.spec b/packaging/machine-learning-api.spec index 8a7da1e5..ebbb00ba 100644 --- a/packaging/machine-learning-api.spec +++ b/packaging/machine-learning-api.spec @@ -280,6 +280,14 @@ Group: Machine Learning/ML Framework Requires: capi-machine-learning-service = %{version}-%{release} %description -n capi-machine-learning-service-devel-static Static library of Tizen Machine Learning Service API. + +%package -n capi-machine-learning-experimental-devel +Summary: Experimental features for Tizen Machine Learning API +Group: Machine Learning/ML Framework +Requires: capi-machine-learning-inference-devel = %{version}-%{release} +Requires: capi-machine-learning-service-devel = %{version}-%{release} +%description -n capi-machine-learning-experimental-devel +Experimental features for Tizen Machine Learning API. %endif %if 0%{?unit_test} @@ -542,6 +550,9 @@ install -m 0755 packaging/run-unittest.sh %{buildroot}%{_bindir}/tizen-unittests %files -n capi-machine-learning-service-devel-static %{_libdir}/libcapi-ml-service.a + +%files -n capi-machine-learning-experimental-devel +%{_includedir}/nnstreamer/ml-api-experimental.h %endif %if 0%{?unit_test} diff --git a/tests/capi/unittest_capi_inference.cc b/tests/capi/unittest_capi_inference.cc index 076b1b78..5bbf4308 100644 --- a/tests/capi/unittest_capi_inference.cc +++ b/tests/capi/unittest_capi_inference.cc @@ -13,6 +13,7 @@ #include #include #include +#include #include #include #include