From fd4ffc5822815179194ef1a89d652204fcba4a5d Mon Sep 17 00:00:00 2001 From: Yongjoo Ahn Date: Fri, 17 Jan 2025 15:46:04 +0900 Subject: [PATCH] [doc] Add doxygen tags - Add doxygen tags to all source codes. Signed-off-by: Yongjoo Ahn --- doc/hal_ml_doc.h | 34 +++++++++ include/hal-ml-interface-1.h | 47 ++++++++++++- include/hal-ml-interface.h | 20 ++++++ include/hal-ml-types.h | 29 +++++++- include/hal-ml.h | 133 +++++++++++++++++++++++++++++++++-- src/hal-api-ml.c | 28 +++++--- 6 files changed, 273 insertions(+), 18 deletions(-) create mode 100644 doc/hal_ml_doc.h diff --git a/doc/hal_ml_doc.h b/doc/hal_ml_doc.h new file mode 100644 index 0000000..3f03f3c --- /dev/null +++ b/doc/hal_ml_doc.h @@ -0,0 +1,34 @@ +/** + * High level documentation of the HAL ML + * Copyright (C) 2025 Yongjoo Ahn + * + * SPDX-License-Identifier: Apache-2.0 + * + * @file hal_ml_doc.h + * @date 15 Jan 2025 + * @brief High level documentation of the HAL ML + * @author Yongjoo Ahn + * @see https://github.com/nnstreamer/nnstremaer + * @bug No known bugs except for NYI items + * + * @details + * This file contains high level documentation of the HAL ML. + */ + +#ifndef __TIZEN_HAL_ML_DOC_H__ +#define __TIZEN_HAL_ML_DOC_H__ + + +/** + * @defgroup HALAPI_HAL_ML_MODULE ML + * @brief The @ref HALAPI_HAL_ML_MODULE provides functions for ml. + * + * @section HALAPI_HAL_ML_MODULE_HEADER Required Header + * \#include + * + * @section HALAPI_HAL_ML_MODULE_OVERVIEW Overview + * Tizen ML API may require a hardware device to accelerate its job. + * This HAL ML provides an interface for Tizen ML API (NNStreamer's tensor_filter subplugin) to use such hardware acceleration devices (NPU, ...) if available. + */ + +#endif /* __TIZEN_HAL_ML_DOC_H__ */ diff --git a/include/hal-ml-interface-1.h b/include/hal-ml-interface-1.h index 38b75a6..80b00fe 100644 --- a/include/hal-ml-interface-1.h +++ b/include/hal-ml-interface-1.h @@ -1,3 +1,24 @@ +/** + * HAL (Hardware Abstract Layer) interface API for ML + * + * Copyright (C) 2025 Yongjoo Ahn + * + * SPDX-License-Identifier: Apache-2.0 + * + * @file hal-ml-interface-1.h + * @date 15 Jan 2025 + * @brief HAL (Hardware Abstract Layer) interface API for ML + * @author Yongjoo Ahn + * @see https://github.com/nnstreamer/nnstremaer + * @bug No known bugs except for NYI items + * + * @details + * This is the header file for the HAL ML interface version 1. + */ + +#ifndef __HAL_ML_INTERFACE_1__ +#define __HAL_ML_INTERFACE_1__ + #include "tensor_typedef.h" #include "nnstreamer_plugin_api_filter.h" @@ -5,20 +26,42 @@ #ifdef __cplusplus extern "C" { -#endif +#endif /* __cplusplus */ +/** + * @addtogroup HALAPI_HAL_ML_MODULE + * @{ + */ + +/** + * @brief The HAL backend structure for ML. This should be implemented by each HAL backend. + * @since HAL_MODULE_ML 1.0 + */ typedef struct _hal_backend_ml_funcs { + /**< Initialize HL backend handle */ int (*init)(void **backend_private); + /**< Deinitialize HL backend handle */ int (*deinit)(void *backend_private); + /**< Configure ml framework */ int (*configure_instance)(void *backend_private, const GstTensorFilterProperties *prop); + /**< Invoke */ int (*invoke)(void *backend_private, const GstTensorMemory *input, GstTensorMemory *output); + /**< Invoke dynamic */ int (*invoke_dynamic)(void *backend_private, GstTensorFilterProperties *prop, const GstTensorMemory *input, GstTensorMemory *output); + /**< Get framework info */ int (*get_framework_info)(void *backend_private, GstTensorFilterFrameworkInfo *framework_info); + /**< Get model info */ int (*get_model_info)(void *backend_private, model_info_ops ops, GstTensorsInfo *in_info, GstTensorsInfo *out_info); + /**< Handle event */ int (*event_handler)(void *backend_private, event_ops ops, GstTensorFilterFrameworkEventData *data); } hal_backend_ml_funcs; +/** + * @} + */ + #ifdef __cplusplus } -#endif +#endif /* __cplusplus */ +#endif /* __HAL_ML_INTERFACE_1__ */ diff --git a/include/hal-ml-interface.h b/include/hal-ml-interface.h index 7ab165e..054ca4f 100644 --- a/include/hal-ml-interface.h +++ b/include/hal-ml-interface.h @@ -1 +1,21 @@ +/** + * HAL (Hardware Abstract Layer) interface API for ML + * + * Copyright (C) 2025 Yongjoo Ahn + * + * SPDX-License-Identifier: Apache-2.0 + * + * @file hal-ml-interface.h + * @date 15 Jan 2025 + * @brief HAL (Hardware Abstract Layer) interface API for ML + * @author Yongjoo Ahn + * @see https://github.com/nnstreamer/nnstremaer + * @bug No known bugs except for NYI items + */ + +#ifndef __HAL_ML_INTERFACE__ +#define __HAL_ML_INTERFACE__ + #include "hal-ml-interface-1.h" + +#endif /* __HAL_ML_INTERFACE__ */ diff --git a/include/hal-ml-types.h b/include/hal-ml-types.h index 737319b..77f577c 100644 --- a/include/hal-ml-types.h +++ b/include/hal-ml-types.h @@ -1,3 +1,18 @@ +/** + * Define types for HAL ML + * + * Copyright (C) 2025 Yongjoo Ahn + * + * SPDX-License-Identifier: Apache-2.0 + * + * @file hal-ml-types.h + * @date 15 Jan 2025 + * @brief Define types for HAL ML + * @author Yongjoo Ahn + * @see https://github.com/nnstreamer/nnstremaer + * @bug No known bugs except for NYI items + */ + #ifndef __HAL_ML_TYPES__ #define __HAL_ML_TYPES__ @@ -8,6 +23,15 @@ extern "C" { #endif /* __cplusplus */ +/** + * @addtogroup HAL_ML_MODULE + * @{ + */ + +/** + * @brief Enumeration for the error codes of hal-ml + * @since HAL_MODULE_ML 1.0 + */ typedef enum hal_ml_error { HAL_ML_ERROR_NONE = 0, HAL_ML_ERROR_INVALID_PARAMETER = -1, @@ -19,9 +43,10 @@ typedef enum hal_ml_error { HAL_ML_ERROR_RUNTIME_ERROR = -7, } hal_ml_error_e; +/** + * @} + */ -typedef void *hal_ml_h; -typedef void *hal_ml_param_h; #ifdef __cplusplus } diff --git a/include/hal-ml.h b/include/hal-ml.h index d1f6098..b6e11b4 100644 --- a/include/hal-ml.h +++ b/include/hal-ml.h @@ -1,22 +1,147 @@ -#include "hal-ml-types.h" +/** + * HAL (Hardware Abstract Layer) API for ML + * + * Copyright (C) 2025 Yongjoo Ahn + * + * SPDX-License-Identifier: Apache-2.0 + * + * @file hal-ml.h + * @date 15 Jan 2025 + * @brief HAL (Hardware Abstract Layer) API for ML + * @author Yongjoo Ahn + * @see https://github.com/nnstreamer/nnstremaer + * @bug No known bugs except for NYI items + * + * @details + * This HAL ML provides an interface for Tizen ML API (NNStreamer's tensor_filter subplugin) + * to use hardware acceleration devices (NPU, ...). + */ + +#ifndef __HAL_ML__ +#define __HAL_ML__ + +#include #ifdef __cplusplus extern "C" { -#endif +#endif /* __cplusplus */ + +/** + * @addtogroup HAL_ML_MODULE + * @{ + */ + +/** + * @brief A handle for hal-ml instance + * @since HAL_MODULE_ML 1.0 + */ typedef void *hal_ml_h; + +/** + * @brief A handle for hal-ml-param instance + * @since HAL_MODULE_ML 1.0 + */ typedef void *hal_ml_param_h; + +/** + * @brief Creates hal-ml-param instance + * @since HAL_MODULE_ML 1.0 + * @remarks The @a param should be released using hal_ml_param_destroy(). + * @param[out] option Newly created option handle is returned. + * @return @c 0 on success. Otherwise a negative error value. + * @retval #HAL_ML_ERROR_NONE Successful. + * @retval #HAL_ML_ERROR_INVALID_PARAMETER Fail. The parameter is invalid. + * @retval #HAL_ML_ERROR_OUT_OF_MEMORY Failed to allocate required memory. + */ int hal_ml_param_create(hal_ml_param_h *param); + +/** + * @brief Destroys hal-ml-param instance + * @since HAL_MODULE_ML 1.0 + * @param[in] param The handle of the param instance to be destroyed. + * @return @c 0 on success. Otherwise a negative error value. + * @retval #HAL_ML_ERROR_NONE Successful. + * @retval #HAL_ML_ERROR_INVALID_PARAMETER Fail. The parameter is invalid. + */ int hal_ml_param_destroy(hal_ml_param_h param); + +/** + * @brief Sets a parameter for hal-ml-param instance + * @since HAL_MODULE_ML 1.0 + * @param[in] param The handle of the param instance. + * @param[in] key The key of the parameter to set. + * @param[in] value The value of the parameter to set. + * @return @c 0 on success. Otherwise a negative error value. + * @retval #HAL_ML_ERROR_NONE Successful. + * @retval #HAL_ML_ERROR_INVALID_PARAMETER Fail. The parameter is invalid. + */ int hal_ml_param_set(hal_ml_param_h param, const char *key, void *value); -// int hal_ml_param_get(hal_ml_param_h param, const char *key, void **value); +/** + * @brief Creates hal-ml instance + * @since HAL_MODULE_ML 1.0 + * @remarks The @a handle should be released using hal_ml_destroy(). + * @param[in] backend_name The name of the backend to use. + * @param[out] handle Newly created handle is returned. + * @return @c 0 on success. Otherwise a negative error value. + * @retval #HAL_ML_ERROR_NONE Successful. + * @retval #HAL_ML_ERROR_INVALID_PARAMETER Fail. The parameter is invalid. + * @retval #HAL_ML_ERROR_OUT_OF_MEMORY Failed to allocate required memory. + */ int hal_ml_create(const char *backend_name, hal_ml_h *handle); + +/** + * @brief Destroys hal-ml instance + * @since HAL_MODULE_ML 1.0 + * @param[in] handle The handle of the instance to be destroyed. + * @return @c 0 on success. Otherwise a negative error value. + * @retval #HAL_ML_ERROR_NONE Successful. + * @retval #HAL_ML_ERROR_INVALID_PARAMETER Fail. The parameter is invalid. + */ int hal_ml_destroy(hal_ml_h handle); + +/** + * @brief Sends a request to hal-ml instance + * @since HAL_MODULE_ML 1.0 + * @param[in] handle The handle of the instance. + * @param[in] request_name The name of the request. + * @param[in] param The parameters for the request. + * @return @c 0 on success. Otherwise a negative error value. + * @retval #HAL_ML_ERROR_NONE Successful. + * @retval #HAL_ML_ERROR_INVALID_PARAMETER Fail. The parameter is invalid. + */ int hal_ml_request(hal_ml_h handle, const char *request_name, hal_ml_param_h param); +/** + * @brief Invokes the hal-ml instance with the given data. + * @since HAL_MODULE_ML 1.0 + * @param[in] handle The handle of the instance. + * @param[in] input The input data for the invoke. + * @param[in, out] output The output data for the invoke. + * @return @c 0 on success. Otherwise a negative error value. + * @retval #HAL_ML_ERROR_NONE Successful. + * @retval #HAL_ML_ERROR_INVALID_PARAMETER Fail. The parameter is invalid. + */ int hal_ml_request_invoke(hal_ml_h handle, const void *input, void *output); + +/** + * @brief Invoke dynamic the hal-ml instance with the given data. + * @since HAL_MODULE_ML 1.0 + * @param[in] handle The handle of the instance. + * @param[in, out] prop The properties for the invoke dynamic. + * @param[in] input The input data for the invoke. + * @param[in, out] output The output data for the invoke. + * @return @c 0 on success. Otherwise a negative error value. + * @retval #HAL_ML_ERROR_NONE Successful. + * @retval #HAL_ML_ERROR_INVALID_PARAMETER Fail. The parameter is invalid. + */ int hal_ml_request_invoke_dynamic(hal_ml_h handle, void *prop, const void *input, void *output); +/** + * @} + */ + #ifdef __cplusplus } -#endif \ No newline at end of file +#endif /* __cplusplus */ +#endif /* __HAL_ML__ */ diff --git a/src/hal-api-ml.c b/src/hal-api-ml.c index f20b9db..c3d18db 100644 --- a/src/hal-api-ml.c +++ b/src/hal-api-ml.c @@ -1,4 +1,21 @@ -/* SPDX-License-Identifier: Apache-2.0 */ +/** + * HAL (Hardware Abstract Layer) API for ML + * + * Copyright (C) 2025 Yongjoo Ahn + * + * SPDX-License-Identifier: Apache-2.0 + * + * @file hal-api-ml.c + * @date 15 Jan 2025 + * @brief HAL (Hardware Abstract Layer) API for ML + * @author Yongjoo Ahn + * @see https://github.com/nnstreamer/nnstremaer + * @bug No known bugs except for NYI items + * + * @details + * This HAL ML provides an interface for Tizen ML API (NNStreamer's tensor_filter subplugin) + * to use hardware acceleration devices (NPU, ...). + */ #include @@ -7,21 +24,12 @@ #include "hal-ml-interface.h" #include "hal-ml.h" -#if defined(__TIZEN__) #include #define LOG_TAG "HAL_ML" #define _D(fmt, args...) SLOGD(fmt, ##args) #define _I(fmt, args...) SLOGI(fmt, ##args) #define _W(fmt, args...) SLOGW(fmt, ##args) #define _E(fmt, args...) SLOGE(fmt, ##args) -#else -#include - -#define _D g_debug -#define _I g_info -#define _W g_warning -#define _E g_critical -#endif typedef struct _hal_ml_s { -- 2.34.1