NGraph FrontEnd Manager - Basic API (openvinotoolkit#5470)

* NGraph - FrontEndManager - common API
Added Mock frontend for unit testing

* Comment out installation rules

* Fixed review comment
Introduced environment variable OV_FRONTEND_PATH for frontend paths

* Additional cmake cleanup

* More fixes of cmakelists

* Changing template file name for frontends

* Changed copyrights

* Reuse ngraph-utils for file-related operations

* Correct of frontend file extension for macos
More code coverage

* Renamed all methods to according to ngraph-style
In case of unset or empty OV_FRONTENT_PATH - load plugins from current working directory

* Fix review comments
Add clang format target for frontend_manager and mock frontend plugin

* Update docs for FrontEndCapabilities

* Use constants for flags instead of 'enum'

* clang style fix

* Fix comment: using namespace ngraph...

* Fix comment: use replace "frontend_manager" with ${TARGET_NAME} in CMakeLists.txt

* Comment fix: rename 'generic' folder to 'frontend_manager'

* Update documentation comments

* Set FrontEndManager class as 'final'

* Apply review comments

* renamed get_place_by_name_and... to get_place_by_operation_name_and...

* Separated frontend_manager.hpp into 4 header files

ngraph/CMakeLists.txt

@@ -26,6 +26,15 @@ set(NGRAPH_INCLUDE_PATH
     ${CMAKE_CURRENT_SOURCE_DIR}/core/include
 )
 
+set(FRONTEND_INCLUDE_PATH
+    ${CMAKE_CURRENT_SOURCE_DIR}/frontend/frontend_manager/include
+)
+
+# Will be used by frontends to construct frontend-specific source location paths
+set(FRONTEND_BASE_PATH
+    ${CMAKE_CURRENT_SOURCE_DIR}/frontend
+)
+
 if (APPLE)
     # Enable MACOS_RPATH by default.
     cmake_policy(SET CMP0042 NEW)

ngraph/frontend/CMakeLists.txt

@@ -2,6 +2,8 @@
 # SPDX-License-Identifier: Apache-2.0
 #
 
+add_subdirectory(frontend_manager)
+
 if (NGRAPH_ONNX_IMPORT_ENABLE)
     add_subdirectory(onnx_common)
     add_subdirectory(onnx_import)

ngraph/frontend/frontend_manager/CMakeLists.txt

@@ -0,0 +1,35 @@
+# Copyright (C) 2018-2021 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+#
+
+set(TARGET_NAME "frontend_manager")
+
+file(GLOB_RECURSE LIBRARY_SRC ${CMAKE_CURRENT_SOURCE_DIR}/src/*.cpp)
+file(GLOB_RECURSE LIBRARY_HEADERS ${CMAKE_CURRENT_SOURCE_DIR}/src/*.hpp)
+file(GLOB_RECURSE LIBRARY_PUBLIC_HEADERS ${CMAKE_CURRENT_SOURCE_DIR}/include/*.hpp)
+
+set(FRONTEND_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/include)
+
+source_group("src" FILES ${LIBRARY_SRC})
+source_group("include" FILES ${LIBRARY_HEADERS})
+source_group("public include" FILES ${LIBRARY_PUBLIC_HEADERS})
+
+# Create shared library
+add_library(${TARGET_NAME} SHARED ${LIBRARY_SRC} ${LIBRARY_HEADERS} ${LIBRARY_PUBLIC_HEADERS})
+add_library(ngraph::${TARGET_NAME} ALIAS ${TARGET_NAME})
+
+target_link_libraries(${TARGET_NAME} PRIVATE ${CMAKE_DL_LIBS} ngraph)
+
+add_clang_format_target(${TARGET_NAME}_clang FOR_TARGETS ${TARGET_NAME})
+
+if(COMMAND ie_add_vs_version_file)
+    ie_add_vs_version_file(NAME ${TARGET_NAME}
+                           FILEDESCRIPTION "Manager of OpenVINO nGraph Frontends")
+endif()
+
+set(FRONTEND_INSTALL_INCLUDE "${NGRAPH_INSTALL_INCLUDE}/ngraph/frontend/frontend_manager")
+target_include_directories(${TARGET_NAME} PUBLIC $<BUILD_INTERFACE:${FRONTEND_INCLUDE_DIR}>
+                                                       $<INSTALL_INTERFACE:${FRONTEND_INSTALL_INCLUDE}>)
+target_include_directories(${TARGET_NAME} PRIVATE ${NGRAPH_INCLUDE_PATH} ${FRONTEND_INCLUDE_DIR})
+
+target_include_directories(${TARGET_NAME} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)

ngraph/frontend/frontend_manager/include/frontend_manager/frontend.hpp

@@ -0,0 +1,102 @@
+// Copyright (C) 2018-2021 Intel Corporation
+// SPDX-License-Identifier: Apache-2.0
+//
+
+#pragma once
+
+#include <memory>
+#include <string>
+#include <vector>
+#include "frontend_manager_defs.hpp"
+#include "input_model.hpp"
+#include "ngraph/function.hpp"
+
+namespace ngraph
+{
+    namespace frontend
+    {
+        /// \brief An interface for identifying a frontend for a particular framework.
+        /// Provides an ability to load and convert of input model
+        class FRONTEND_API FrontEnd
+        {
+        public:
+            typedef std::shared_ptr<FrontEnd> Ptr;
+
+            FrontEnd();
+
+            virtual ~FrontEnd();
+
+            /// \brief Loads an input model by specified model file path
+            /// If model is stored in several files (e.g. model topology and model weights) -
+            /// frontend implementation is responsible to handle this case, generally frontend may
+            /// retrieve other file names from main file
+            /// \param path Main model file path
+            /// \return Loaded input model
+            virtual InputModel::Ptr load_from_file(const std::string& path) const;
+
+            /// \brief Loads an input model by specified number of model files
+            /// This shall be used for cases when client knows all model files (model, weights, etc)
+            /// \param paths Array of model files
+            /// \return Loaded input model
+            virtual InputModel::Ptr load_from_files(const std::vector<std::string>& paths) const;
+
+            /// \brief Loads an input model by already loaded memory buffer
+            /// Memory structure is frontend-defined and is not specified in generic API
+            /// \param model Model memory buffer
+            /// \return Loaded input model
+            virtual InputModel::Ptr load_from_memory(const void* model) const;
+
+            /// \brief Loads an input model from set of memory buffers
+            /// Memory structure is frontend-defined and is not specified in generic API
+            /// \param modelParts Array of model memory buffers
+            /// \return Loaded input model
+            virtual InputModel::Ptr
+                load_from_memory_fragments(const std::vector<const void*>& modelParts) const;
+
+            /// \brief Loads an input model by input stream representing main model file
+            /// \param stream Input stream of main model
+            /// \return Loaded input model
+            virtual InputModel::Ptr load_from_stream(std::istream& stream) const;
+
+            /// \brief Loads an input model by input streams representing all model files
+            /// \param streams Array of input streams for model
+            /// \return Loaded input model
+            virtual InputModel::Ptr
+                load_from_streams(const std::vector<std::istream*>& streams) const;
+
+            /// \brief Completely convert and normalize entire function, throws if it is not
+            /// possible
+            /// \param model Input model
+            /// \return fully converted nGraph function
+            virtual std::shared_ptr<ngraph::Function> convert(InputModel::Ptr model) const;
+
+            /// \brief Completely convert the remaining, not converted part of a function.
+            /// \param partiallyConverted partially converted nGraph function
+            /// \return fully converted nGraph function
+            virtual std::shared_ptr<ngraph::Function>
+                convert(std::shared_ptr<ngraph::Function> partiallyConverted) const;
+
+            /// \brief Convert only those parts of the model that can be converted leaving others
+            /// as-is. Converted parts are not normalized by additional transformations; normalize
+            /// function or another form of convert function should be called to finalize the
+            /// conversion process.
+            /// \param model Input model
+            /// \return partially converted nGraph function
+            virtual std::shared_ptr<ngraph::Function>
+                convert_partially(InputModel::Ptr model) const;
+
+            /// \brief Convert operations with one-to-one mapping with decoding nodes.
+            /// Each decoding node is an nGraph node representing a single FW operation node with
+            /// all attributes represented in FW-independent way.
+            /// \param model Input model
+            /// \return nGraph function after decoding
+            virtual std::shared_ptr<ngraph::Function> decode(InputModel::Ptr model) const;
+
+            /// \brief Runs normalization passes on function that was loaded with partial conversion
+            /// \param function partially converted nGraph function
+            virtual void normalize(std::shared_ptr<ngraph::Function> function) const;
+        };
+
+    } // namespace frontend
+
+} // namespace ngraph

ngraph/frontend/frontend_manager/include/frontend_manager/frontend_manager.hpp

@@ -0,0 +1,122 @@
+// Copyright (C) 2018-2021 Intel Corporation
+// SPDX-License-Identifier: Apache-2.0
+//
+
+#pragma once
+
+#include <memory>
+#include <string>
+#include "frontend.hpp"
+#include "frontend_manager_defs.hpp"
+
+namespace ngraph
+{
+    namespace frontend
+    {
+        /// Capabilities for requested FrontEnd
+        /// In general, frontend implementation may be divided into several libraries by capability
+        /// level It will allow faster load of frontend when only limited usage is expected by
+        /// client application as well as binary size can be minimized by removing not needed parts
+        /// from application's package
+        namespace FrontEndCapabilities
+        {
+            /// \brief Just reading and conversion, w/o any modifications; intended to be used in
+            /// Reader
+            static const int FEC_DEFAULT = 0;
+
+            /// \brief Topology cutting capability
+            static const int FEC_CUT = 1;
+
+            /// \brief Query entities by names, renaming and adding new names for operations and
+            /// tensors
+            static const int FEC_NAMES = 2;
+
+            /// \brief Partial model conversion and decoding capability
+            static const int FEC_WILDCARDS = 4;
+        }; // namespace FrontEndCapabilities
+
+        // -------------- FrontEndManager -----------------
+        using FrontEndCapFlags = int;
+        using FrontEndFactory = std::function<FrontEnd::Ptr(FrontEndCapFlags fec)>;
+
+        /// \brief Frontend management class, loads available frontend plugins on construction
+        /// Allows load of frontends for particular framework, register new and list available
+        /// frontends This is a main frontend entry point for client applications
+        class FRONTEND_API FrontEndManager final
+        {
+        public:
+            /// \brief Default constructor. Searches and loads of available frontends
+            FrontEndManager();
+
+            /// \brief Default move constructor
+            FrontEndManager(FrontEndManager&&);
+
+            /// \brief Default move assignment operator
+            FrontEndManager& operator=(FrontEndManager&&);
+
+            /// \brief Default destructor
+            ~FrontEndManager();
+
+            /// \brief Loads frontend by name of framework and capabilities
+            ///
+            /// \param framework Framework name. Throws exception if name is not in list of
+            /// available frontends
+            ///
+            /// \param fec Frontend capabilities. It is recommended to use only
+            /// those capabilities which are needed to minimize load time
+            ///
+            /// \return Frontend interface for further loading of models
+            FrontEnd::Ptr
+                load_by_framework(const std::string& framework,
+                                  FrontEndCapFlags fec = FrontEndCapabilities::FEC_DEFAULT);
+
+            /// \brief Loads frontend by model file path. Selects and loads appropriate frontend
+            /// depending on model file extension and other file info (header)
+            ///
+            /// \param framework
+            /// Framework name. Throws exception if name is not in list of available frontends
+            ///
+            /// \param fec Frontend capabilities. It is recommended to use only those capabilities
+            /// which are needed to minimize load time
+            ///
+            /// \return Frontend interface for further loading of model
+            FrontEnd::Ptr load_by_model(const std::string& path,
+                                        FrontEndCapFlags fec = FrontEndCapabilities::FEC_DEFAULT);
+
+            /// \brief Gets list of registered frontends
+            std::vector<std::string> get_available_front_ends() const;
+
+            /// \brief Register frontend with name and factory creation method
+            ///
+            /// \param name Name of front end
+            ///
+            /// \param creator Creation factory callback. Will be called when frontend is about to
+            /// be created
+            void register_front_end(const std::string& name, FrontEndFactory creator);
+
+        private:
+            class Impl;
+
+            std::unique_ptr<Impl> m_impl;
+        };
+
+        // --------- Plugin exporting information --------------
+
+        /// \brief Each frontend plugin is responsible to export GetAPIVersion function returning
+        /// version of frontend API used for this plugin
+        /// If version is not matched with OV_FRONTEND_API_VERSION - plugin will not be loaded by
+        /// FrontEndManager
+        using FrontEndVersion = uint64_t;
+
+        /// \brief Each frontend plugin is responsible to export GetFrontEndData function returning
+        /// heap-allocated pointer to this structure. Will be used by FrontEndManager during loading
+        /// of plugins
+        struct FrontEndPluginInfo
+        {
+            std::string m_name;
+            FrontEndFactory m_creator;
+        };
+
+    } // namespace frontend
+
+} // namespace ngraph

ngraph/frontend/frontend_manager/include/frontend_manager/frontend_manager_defs.hpp

@@ -0,0 +1,17 @@
+// Copyright (C) 2018-2021 Intel Corporation
+// SPDX-License-Identifier: Apache-2.0
+//
+
+#pragma once
+
+#include "ngraph/visibility.hpp"
+
+// Increment each time when FrontEnd/InputModel/Place interface is changed
+#define OV_FRONTEND_API_VERSION 1
+
+// Defined if cmake is building the frontend_manager DLL (instead of using it)
+#ifdef frontend_manager_EXPORTS
+#define FRONTEND_API NGRAPH_HELPER_DLL_EXPORT
+#else
+#define FRONTEND_API NGRAPH_HELPER_DLL_IMPORT
+#endif // frontend_manager_EXPORTS