build(tvm_utility): remove download logic from CMake and update documentation

common/tvm_utility/.gitignore

@@ -1,2 +0,0 @@
-artifacts/**/*.jpg
-data/

common/tvm_utility/CMakeLists.txt

@@ -29,15 +29,19 @@ set(TVM_UTILITY_NODE_LIB_HEADERS
 ament_auto_add_library(${PROJECT_NAME} SHARED ${TVM_UTILITY_NODE_LIB_HEADERS})
 set_target_properties(${PROJECT_NAME} PROPERTIES LINKER_LANGUAGE CXX)
 
-if(BUILD_TESTING)
+set(BUILD_EXAMPLE OFF CACHE BOOL "enable build yolo_v2_tiny")
+
+if(BUILD_TESTING OR BUILD_EXAMPLE)
+  find_package(OpenCV REQUIRED)
+  set(tvm_runtime_DIR ${tvm_vendor_DIR})
+  find_package(tvm_runtime CONFIG REQUIRED)
   # Get target backend
   set(${PROJECT_NAME}_BACKEND llvm CACHE STRING "${PROJECT_NAME} neural network backend")
+endif()
 
+if(BUILD_TESTING)
   # compile each folder inside test/ as a test case
   find_package(ament_cmake_gtest REQUIRED)
-  find_package(OpenCV REQUIRED)
-  set(tvm_runtime_DIR ${tvm_vendor_DIR})
-  find_package(tvm_runtime CONFIG REQUIRED)
 
   set(TEST_ARTIFACTS "${CMAKE_CURRENT_LIST_DIR}/artifacts")
   file(GLOB TEST_CASES test/*)
@@ -47,17 +51,11 @@ if(BUILD_TESTING)
     endif()
     # the folder name becomes the test case name
     file(RELATIVE_PATH TEST_CASE_NAME ${CMAKE_CURRENT_LIST_DIR}/test ${TEST_FOLDER})
-
     # Get neural network.
     set(NN_DEPENDENCY "")
-    get_neural_network(${TEST_CASE_NAME} ${${PROJECT_NAME}_BACKEND} NN_DEPENDENCY)
+    get_neural_network(${TEST_CASE_NAME}_${CMAKE_SYSTEM_PROCESSOR} ${${PROJECT_NAME}_BACKEND} NN_DEPENDENCY)
 
     if(NOT NN_DEPENDENCY STREQUAL "")
-      if(TEST_CASE_NAME STREQUAL "yolo_v2_tiny" AND
-          NOT EXISTS ${TEST_ARTIFACTS}/yolo_v2_tiny/test_image_0.jpg)
-        message(WARNING "Missing image artifact for yolo_v2_tiny, skipping test")
-        continue()
-      endif()
       # add all cpp files in the folder to the target
       file(GLOB TEST_CASE_SOURCES ${TEST_FOLDER}/*.cpp)
       ament_add_gtest(${TEST_CASE_NAME} ${TEST_CASE_SOURCES})
@@ -75,7 +73,7 @@ if(BUILD_TESTING)
       target_include_directories("${TEST_CASE_NAME}" SYSTEM PUBLIC
         "${OpenCV_INCLUDE_DIRS}"
         "${tvm_utility_FOUND_INCLUDE_DIRS}"
-        "data/models"
+        "data/models/${TEST_CASE_NAME}_${CMAKE_SYSTEM_PROCESSOR}"
         "include"
       )
 
@@ -93,5 +91,60 @@ if(BUILD_TESTING)
   endforeach()
 endif()
 
+if(BUILD_EXAMPLE)
+  # compile each folder inside example/ as an example
+  find_package(rclcpp REQUIRED)
+
+  set(EXAMPLE_ARTIFACTS "${CMAKE_CURRENT_LIST_DIR}/artifacts")
+  file(GLOB EXAMPLE_CASES example/*)
+  foreach(EXAMPLE_FOLDER ${EXAMPLE_CASES})
+    if(NOT IS_DIRECTORY ${EXAMPLE_FOLDER})
+      continue()
+    endif()
+    # the folder name becomes the example name
+    file(RELATIVE_PATH EXAMPLE_NAME ${CMAKE_CURRENT_LIST_DIR}/example ${EXAMPLE_FOLDER})
+    # Get neural network.
+    set(NN_DEPENDENCY "")
+    get_neural_network(${EXAMPLE_NAME} ${${PROJECT_NAME}_BACKEND} NN_DEPENDENCY)
+
+    if(NOT NN_DEPENDENCY STREQUAL "")
+      if(EXAMPLE_NAME STREQUAL "yolo_v2_tiny" AND
+          NOT EXISTS ${EXAMPLE_ARTIFACTS}/yolo_v2_tiny/test_image_0.jpg)
+        message(WARNING "Missing image artifact for yolo_v2_tiny, skipping example")
+        continue()
+      endif()
+      # add all cpp files in the folder to the target
+      file(GLOB EXAMPLE_SOURCES ${EXAMPLE_FOLDER}/*.cpp)
+      ament_auto_add_executable(${EXAMPLE_NAME} ${EXAMPLE_SOURCES})
+      ament_target_dependencies(${EXAMPLE_NAME}
+        "ament_index_cpp"
+        "tvm_vendor"
+        "rclcpp"
+      )
+      add_dependencies(${EXAMPLE_NAME} ${NN_DEPENDENCY})
+
+      target_link_libraries("${EXAMPLE_NAME}"
+        "${OpenCV_LIBRARIES}"
+        "${tvm_runtime_LIBRARIES}"
+      )
+
+      target_include_directories("${EXAMPLE_NAME}" SYSTEM PUBLIC
+        "${OpenCV_INCLUDE_DIRS}"
+        "${tvm_utility_FOUND_INCLUDE_DIRS}"
+        "data/models"
+        "include"
+      )
+
+    else()
+      message(WARNING "No model is generated for ${EXAMPLE_FOLDER} example")
+    endif()
+
+  endforeach()
+endif()
+
 list(APPEND ${PROJECT_NAME}_CONFIG_EXTRAS "${PROJECT_NAME}-extras.cmake")
-ament_auto_package()
+# ament_auto_package()
+ament_auto_package(
+  INSTALL_TO_SHARE
+  launch
+  artifacts)

common/tvm_utility/README.md

@@ -41,7 +41,7 @@ The earliest supported version depends on each package making use of the inferen
 
 #### Models
 
-Dependent packages are expected to use the `get_neural_network` cmake function from this package in order to get the compiled TVM models.
+Dependent packages are expected to use the `get_neural_network` cmake function from this package in order to build proper external dependency.
 
 ### Error detection and handling
 
@@ -50,76 +50,55 @@ error description.
 
 ### Neural Networks Provider
 
-This package also provides a utility to get pre-compiled neural networks to packages using them for their inference.
-
 The neural networks are compiled as part of the
 [Model Zoo](https://github.com/autowarefoundation/modelzoo/) CI pipeline and saved to an S3 bucket.
-This package exports cmake variables and functions for ease of access to those neural networks.
 
 The `get_neural_network` function creates an abstraction for the artifact management.
-The artifacts are saved under the source directory of the package making use of the function; under "data/".
-Priority is given to user-provided files, under "data/user/${MODEL_NAME}/".
-If there are no user-provided files, the function tries to reuse previously-downloaded artifacts.
-If there are no previously-downloaded artifacts, and if the `DOWNLOAD_ARTIFACTS` cmake variable is set, they will be downloaded from the bucket.
-Otherwise, nothing happens.
+Users should check if model configuration header file is under "data/user/${MODEL_NAME}/". Otherwise, nothing happens and compilation of the package will be skipped.
 
 The structure inside of the source directory of the package making use of the function is as follow:
 
 ```{text}
 .
 ├── data
-│   ├── downloads
-│   │   ├── ${MODEL 1}-${ARCH 1}-{BACKEND 1}-{VERSION 1}.tar.gz
-│   │   ├── ...
-│   │   └── ${MODEL ...}-${ARCH ...}-{BACKEND ...}-{VERSION ...}.tar.gz
-│   ├── models
-│   │   ├── ${MODEL 1}
-│   │   │   ├── ...
-│   │   │   └── inference_engine_tvm_config.hpp
-│   │   ├── ...
-│   │   └── ${MODEL ...}
-│   │       └── ...
-│   └── user
+│   └── models
 │       ├── ${MODEL 1}
-│       │   ├── deploy_graph.json
-│       │   ├── deploy_lib.so
-│       │   ├── deploy_param.params
 │       │   └── inference_engine_tvm_config.hpp
 │       ├── ...
 │       └── ${MODEL ...}
 │           └── ...
 ```
 
-The `inference_engine_tvm_config.hpp` file needed for compilation by dependent packages is made available under "data/models/${MODEL_NAME}/inference_engine_tvm_config.hpp".
+The `inference_engine_tvm_config.hpp` file needed for compilation by dependent packages should be available under "data/models/${MODEL_NAME}/inference_engine_tvm_config.hpp".
 Dependent packages can use the cmake `add_dependencies` function with the name provided in the `DEPENDENCY` output parameter of `get_neural_network` to ensure this file is created before it gets used.
 
 The other `deploy_*` files are installed to "models/${MODEL_NAME}/" under the `share` directory of the package.
 
-The target version to be downloaded can be overwritten by setting the `MODELZOO_VERSION` cmake variable.
-
-#### Assumptions / Known limits
-
-If several packages make use of the same neural network, it will be downloaded once per package.
-
-In case a requested artifact doesn't exist in the S3 bucket, the error message from ExternalProject is not explicit enough for the user to understand what went wrong.
+The other model files should be stored in autoware_data folder under package folder with the structure:
 
-In case the user manually sets `MODELZOO_VERSION` to "latest", the archive will not be re-downloaded when it gets updated in the S3 bucket (it is not a problem for tagged versions as they are not expected to be updated).
+```{text}
+$HOME/autoware_data
+|     └──${package}
+|        └──models
+|           ├── ${MODEL 1}
+|           |    ├── deploy_graph.json
+|           |    ├── deploy_lib.so
+|           |    └── deploy_param.params
+|           ├── ...
+|           └── ${MODEL ...}
+|                └── ...
+```
 
 #### Inputs / Outputs
 
-Inputs:
-
-- `DOWNLOAD_ARTIFACTS` cmake variable; needs to be set to enable downloading the artifacts
-- `MODELZOO_VERSION` cmake variable; can be used to overwrite the default target version of downloads
-
 Outputs:
 
-- `get_neural_network` cmake function; can be used to get a neural network compiled for a specific backend
+- `get_neural_network` cmake function; create proper external dependency for a package with use of the model provided by the user.
 
 In/Out:
 
 - The `DEPENDENCY` argument of `get_neural_network` can be checked for the outcome of the function.
-  It is an empty string when the neural network couldn't be made available.
+  It is an empty string when the neural network wasn't provided by the user.
 
 ## Security considerations
 

common/tvm_utility/data/models/abs_model_aarch64/deploy_graph.json

@@ -0,0 +1,36 @@
+{
+  "nodes": [
+    {
+      "op": "null",
+      "name": "a",
+      "inputs": []
+    },
+    {
+      "op": "tvm_op",
+      "name": "tvmgen_default_fused_abs",
+      "attrs": {
+        "num_outputs": "1",
+        "num_inputs": "1",
+        "flatten_data": "0",
+        "func_name": "tvmgen_default_fused_abs",
+        "hash": "1be44995aa501758"
+      },
+      "inputs": [[0, 0, 0]]
+    }
+  ],
+  "arg_nodes": [0],
+  "heads": [[1, 0, 0]],
+  "attrs": {
+    "dltype": ["list_str", ["float32", "float32"]],
+    "device_index": ["list_int", [1, 1]],
+    "storage_id": ["list_int", [0, 1]],
+    "shape": [
+      "list_shape",
+      [
+        [2, 2],
+        [2, 2]
+      ]
+    ]
+  },
+  "node_row_ptr": [0, 1, 2]
+}

common/tvm_utility/data/models/abs_model_aarch64/inference_engine_tvm_config.hpp

@@ -0,0 +1,54 @@
+// Copyright 2021 Arm Limited and Contributors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include "tvm_utility/pipeline.hpp"
+
+#ifndef COMMON__TVM_UTILITY__DATA__MODELS__ABS_MODEL_AARCH64__INFERENCE_ENGINE_TVM_CONFIG_HPP_  // NOLINT
+#define COMMON__TVM_UTILITY__DATA__MODELS__ABS_MODEL_AARCH64__INFERENCE_ENGINE_TVM_CONFIG_HPP_
+
+namespace model_zoo
+{
+namespace inf_test
+{
+namespace engine_load
+{
+namespace abs_model
+{
+
+static const tvm_utility::pipeline::InferenceEngineTVMConfig config{
+  {0, 0, 0},  // modelzoo_version
+
+  // cspell: ignore mtriple
+  "abs_model_aarch64",                // network_name
+  "llvm -mtriple=aarch64-linux-gnu",  // network_backend
+
+  "deploy_lib.so",        // network_module_path
+  "deploy_graph.json",    // network_graph_path
+  "deploy_param.params",  // network_params_path
+
+  // cspell: ignore DLCPU
+  kDLCPU,  // tvm_device_type
+  0,       // tvm_device_id
+
+  {{"a", kDLFloat, 32, 1, {2, 2}}},  // network_inputs
+
+  {{"output", kDLFloat, 32, 1, {2, 2}}}  // network_outputs
+};
+
+}  // namespace abs_model
+}  // namespace engine_load
+}  // namespace inf_test
+}  // namespace model_zoo
+#endif  // COMMON__TVM_UTILITY__DATA__MODELS__ABS_MODEL_AARCH64__INFERENCE_ENGINE_TVM_CONFIG_HPP_
+        // NOLINT

common/tvm_utility/data/models/abs_model_x86_64/deploy_graph.json

@@ -0,0 +1,36 @@
+{
+  "nodes": [
+    {
+      "op": "null",
+      "name": "a",
+      "inputs": []
+    },
+    {
+      "op": "tvm_op",
+      "name": "tvmgen_default_fused_abs",
+      "attrs": {
+        "num_outputs": "1",
+        "num_inputs": "1",
+        "flatten_data": "0",
+        "func_name": "tvmgen_default_fused_abs",
+        "hash": "1be44995aa501758"
+      },
+      "inputs": [[0, 0, 0]]
+    }
+  ],
+  "arg_nodes": [0],
+  "heads": [[1, 0, 0]],
+  "attrs": {
+    "dltype": ["list_str", ["float32", "float32"]],
+    "device_index": ["list_int", [1, 1]],
+    "storage_id": ["list_int", [0, 1]],
+    "shape": [
+      "list_shape",
+      [
+        [2, 2],
+        [2, 2]
+      ]
+    ]
+  },
+  "node_row_ptr": [0, 1, 2]
+}