Add mechanism to archive additional objects to bundle (#5275)

Summary:
**Summary**
Added mechanism to archive additional objects to bundle:
- Added a CMake utility function to serialize files and add to Glow binary files
- Enabled this mechanism for the CPUBackend as an example for other backends to use this mechanism (either public or private backends).
- All the `.o` objects located in `glow/lib/Backends/CPU/libobj_cpu` will be automatically serialized and added in a variable called `cpuObjectRegistry` with memory buffers as `llvm::MemoryBufferRef` at glow build-time
- The command line option `-bundle-objects` controls which of the serialized objects will be archived together with the bundle
- The objects can also be chosen dynamically at runtime by using the function: `void LLVMIRGen::addBundleObject()`

**Documentation**
Short doc in the folder where objects should be located.

**Test Plan**
Added unit test in RELEASE_WITH_EXPENSIVE_TESTS.

Pull Request resolved: #5275

Reviewed By: shajrawi

Differential Revision: D26693270

Pulled By: opti-mix

fbshipit-source-id: 6b57e2a56aba238ff673172ec7c352be1dcc0f84

Author: mciprian13

.ci/bundle_with_extra_objects_expected_output.txt

@@ -0,0 +1 @@
+This is extra bundle object file for testing!

.circleci/test.sh

@@ -68,6 +68,14 @@ run_and_check_bundle_with_multiple_entries() {
     cd -
 }
 
+run_and_check_bundle_with_extra_objects() {
+    cd "${GLOW_BUILD_DIR}/bundles/bundle_with_extra_objects/"
+    # Compare console output.
+    ./BundleWithExtraObjects >> raw_results.txt
+    diff raw_results.txt "${GLOW_SRC}/.ci/bundle_with_extra_objects_expected_output.txt"
+    cd -
+}
+
 run_pytorch_tests() {
     cd "${GLOW_SRC}/torch_glow"
     if hash sccache 2>/dev/null; then
@@ -113,6 +121,7 @@ case ${CIRCLE_JOB} in
         run_and_check_resnet50_bundle
         run_and_check_bundle_instrument
         run_and_check_bundle_with_multiple_entries
+        run_and_check_bundle_with_extra_objects
         ;;
     COVERAGE)
         cd "${GLOW_SRC}"

cmake/modules/GlowSerialize.cmake

@@ -0,0 +1,112 @@
+# Copyright (c) Glow Contributors. See CONTRIBUTORS file.
+#
+# 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.
+
+#===============================================================================
+# DESCRIPTION:
+#   CMake utility function used to serialize as C/C++ binary data arrays all the
+#   given input files into a given output directory and generate a C/C++ include
+#   file which defines a std::vector variable with buffer references defined as
+#   llvm::MemoryBufferRef. The output file is generated while running CMake but
+#   the serialization is done during the build. All the given files must have
+#   unique names and the names (without extension) must be valid C identifiers.
+#
+# ARGUMENTS:
+#   INP_FILES       List with input file paths (absolute paths). (MANDATORY)
+#   OUT_DIR         Output directory where files are serialized. (MANDATORY)
+#   OUT_FILE        Output C/C++ file path. (absolute path). (MANDATORY)
+#   OUT_VAR         The name of the vector variable from the output file which
+#                   holds the references for all the memory buffers. (MANDATORY)
+#   OUT_TARGET      The name of the custom output target. This target will be
+#                   used as dependency for other targets using the byproducts of
+#                   the serialization. (MANDATORY)
+#===============================================================================
+function(glow_serialize)
+
+  # Parse arguments (arguments are concatenated with an "ARG_" prefix).
+  set(oneValueArgs OUT_DIR OUT_FILE OUT_VAR OUT_TARGET)
+  set(multiValueArgs INP_FILES)
+  cmake_parse_arguments("ARG" "" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
+
+  # Check function parameters.
+  # We do not check "ARG_INP_FILES" since it is allowed to be empty.
+
+  if (NOT ARG_OUT_DIR)
+    message(FATAL_ERROR "OUT_DIR argument is mandatory!")
+  endif()
+
+  if (NOT ARG_OUT_FILE)
+    message(FATAL_ERROR "OUT_FILE argument is mandatory!")
+  endif()
+
+  if (NOT ARG_OUT_VAR)
+    message(FATAL_ERROR "OUT_VAR argument is mandatory!")
+  endif()
+
+  if (NOT ARG_OUT_TARGET)
+    message(FATAL_ERROR "OUT_TARGET argument is mandatory!")
+  endif()
+
+  # Make output directory to serialize files.
+  file(MAKE_DIRECTORY ${ARG_OUT_DIR})
+
+  # List with serialized files.
+  set(OUT_FILES)
+
+  # Iterate all the input files.
+  file(WRITE ${ARG_OUT_FILE} "// Auto-generated file. Do not edit!\n\n")
+  foreach(inp_file ${ARG_INP_FILES})
+
+    # Get input file path fields.
+    get_filename_component(file_name ${inp_file} NAME)
+    get_filename_component(file_name_we ${inp_file} NAME_WE)
+    message(STATUS "Serializing file: ${inp_file}")
+
+    # Write C/C++ code for file serialization.
+    file(APPEND ${ARG_OUT_FILE} "static const unsigned char ${file_name_we}_data[] = {\n")
+    file(APPEND ${ARG_OUT_FILE} "  #include \"${file_name}.inc\"\n")
+    file(APPEND ${ARG_OUT_FILE} "};\n\n")
+
+    # Output file path.
+    set(out_file "${ARG_OUT_DIR}/${file_name}.inc")
+    list(APPEND OUT_FILES ${out_file})
+
+    # Add command to serialize file to text.
+    add_custom_command(
+      OUTPUT ${out_file}
+      COMMAND include-bin "${inp_file}" "${out_file}"
+      DEPENDS ${inp_file}
+      WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
+    )
+
+  endforeach()
+
+  # Create vector with buffers defined as llvm::MemoryBufferRef objects.
+  file(APPEND ${ARG_OUT_FILE} "#define MEM_BUFF_REF(name, data) llvm::MemoryBufferRef(llvm::StringRef(reinterpret_cast<const char *>(data), sizeof(data)), name)\n\n")
+  file(APPEND ${ARG_OUT_FILE} "static const std::vector<llvm::MemoryBufferRef> ${ARG_OUT_VAR} = {\n")
+  foreach(inp_file ${ARG_INP_FILES})
+    get_filename_component(file_name ${inp_file} NAME)
+    get_filename_component(file_name_we ${inp_file} NAME_WE)
+    file(APPEND ${ARG_OUT_FILE} "  MEM_BUFF_REF(\"${file_name}\", ${file_name_we}_data),\n")
+  endforeach()
+  file(APPEND ${ARG_OUT_FILE} "};\n\n")
+  file(APPEND ${ARG_OUT_FILE} "#undef MEM_BUFF_REF\n")
+
+  # Add custom target for serialization.
+  add_custom_target(
+    ${ARG_OUT_TARGET}
+    DEPENDS ${OUT_FILES}
+    WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
+  )
+
+endfunction()

examples/bundles/CMakeLists.txt

@@ -2,5 +2,6 @@ if (GLOW_WITH_BUNDLES)
   add_subdirectory(lenet_mnist)
   add_subdirectory(resnet50)
   add_subdirectory(bundle_with_multiple_entries)
+  add_subdirectory(bundle_with_extra_objects)
   add_subdirectory(bundle_instrument)
 endif()

examples/bundles/bundle_with_extra_objects/.gitignore

@@ -0,0 +1,2 @@
+!*.o
+

examples/bundles/bundle_with_extra_objects/CMakeLists.txt

@@ -0,0 +1,52 @@
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${GLOW_BINARY_DIR}/bundles)
+set(LENET_MNIST_BUNDLE_DIR ${GLOW_BINARY_DIR}/examples/bundles/bundle_with_extra_objects)
+set(LENET_MNIST_GLOW_S3 "http://fb-glow-assets.s3.amazonaws.com/models/lenet_mnist")
+set(LENET_MNIST_NET_FILES predict_net.pbtxt predict_net.pb init_net.pb)
+set(MODEL_INPUT_NAME "data")
+set(IMAGES ${GLOW_SOURCE_DIR}/tests/images/mnist)
+
+# Output directory.
+set(BUNDLE_OUTPUT_DIRECTORY ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/bundle_with_extra_objects)
+add_custom_target(BundleWithExtraObjectsDir ALL
+  COMMAND ${CMAKE_COMMAND} -E make_directory ${BUNDLE_OUTPUT_DIRECTORY}
+)
+
+# Executable.
+add_executable(BundleWithExtraObjects $<TARGET_OBJECTS:BundleWithExtraObjectsMain>)
+set_target_properties(BundleWithExtraObjects PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${BUNDLE_OUTPUT_DIRECTORY})
+target_link_libraries(BundleWithExtraObjects ${BUNDLE_OUTPUT_DIRECTORY}/lenet_mnist.o)
+add_dependencies(BundleWithExtraObjects BundleWithExtraObjectsMain BundleWithExtraObjectsNet)
+
+# Bundle.
+add_custom_command(
+  OUTPUT
+    ${BUNDLE_OUTPUT_DIRECTORY}/lenet_mnist.o
+  COMMAND
+    model-compiler -model=${LENET_MNIST_BUNDLE_DIR}/lenet_mnist
+    -model-input=${MODEL_INPUT_NAME},float,[1,1,28,28]
+    -backend=CPU -emit-bundle=${BUNDLE_OUTPUT_DIRECTORY}
+    -bundle-api=static
+    -bundle-objects=test.o
+  DEPENDS
+    model-compiler BundleWithExtraObjectsDir
+)
+add_custom_target(BundleWithExtraObjectsNet DEPENDS ${BUNDLE_OUTPUT_DIRECTORY}/lenet_mnist.o BundleWithExtraObjectsNetFiles)
+
+# Driver program with main function for regular bundle
+add_library(BundleWithExtraObjectsMain OBJECT main.cpp)
+target_compile_options(BundleWithExtraObjectsMain PRIVATE -std=c++11 -g)
+target_include_directories(BundleWithExtraObjectsMain PUBLIC ${BUNDLE_OUTPUT_DIRECTORY})
+add_dependencies(BundleWithExtraObjectsMain BundleWithExtraObjectsNet)
+
+# Network structure and weight files
+foreach(file ${LENET_MNIST_NET_FILES})
+    add_custom_command(
+    OUTPUT
+      ${file}
+    COMMAND
+      wget
+    ARGS
+      "${LENET_MNIST_GLOW_S3}/${file}" -P ${LENET_MNIST_BUNDLE_DIR}/lenet_mnist -nc
+)
+endforeach()
+add_custom_target(BundleWithExtraObjectsNetFiles DEPENDS ${LENET_MNIST_NET_FILES})

examples/bundles/bundle_with_extra_objects/main.cpp

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) Glow Contributors. See CONTRIBUTORS file.
+ *
+ * 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 <stdio.h>
+
+// String variable provided in the extra object archive with the main bundle.
+// The variable has C linkage.
+#ifdef __cplusplus
+extern "C" {
+#endif
+extern const char *testMsg;
+#ifdef __cplusplus
+}
+#endif
+
+int main() { printf("%s", testMsg); }

examples/bundles/bundle_with_extra_objects/test.o

@@ -25,6 +25,7 @@
 #include "glow/Support/Register.h"
 
 #include "llvm/ADT/StringRef.h"
+#include "llvm/Support/MemoryBuffer.h"
 
 #if FACEBOOK_INTERNAL
 namespace folly {
@@ -276,6 +277,16 @@ class Backend : public Named {
     return false;
   };
 
+  /// \returns an array of raw objects which are statically allocated and
+  /// initialized by the backend and which can be used for various purposes,
+  /// for example to store object files (binary code) which are compiled with
+  /// other compilers than clang/LLVM. The raw buffers are encoded as type
+  /// MemoryBufferRef which stores for each buffer a name, a raw pointer
+  /// and a size (in bytes).
+  virtual llvm::ArrayRef<llvm::MemoryBufferRef> getObjectRegistry() const {
+    return llvm::ArrayRef<llvm::MemoryBufferRef>();
+  }
+
 protected:
   /// Parses the graph \F and builds a TraceInfo structure from any found
   /// TraceEventNodes.

include/glow/Backend/Backend.h

@@ -61,6 +61,14 @@ class BundleSaver {
 protected:
   /// Perform memory allocation for a bundle.
   virtual void performBundleMemoryAllocation();
+  /// Create bundle archive by archiving additional object files to the existing
+  /// bundle from \p bundlePath. The object names to be archived are given by
+  /// \p bundleObjects and the object raw content is taken from the object array
+  /// \p bundleObjectRegistry.
+  virtual void createBundleArchive(
+      llvm::StringRef bundlePath,
+      llvm::ArrayRef<llvm::MemoryBufferRef> bundleObjectRegistry,
+      const std::vector<std::string> &bundleObjects);
   /// Save weights for the bundle.
   virtual void saveWeights(llvm::StringRef weightsFileName);
   /// Save header file for the bundle.