Allow installing the Coyote software library (and simulation)

.github/workflows/run_simulation.yaml

@@ -11,10 +11,10 @@
 # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 # copies of the Software, and to permit persons to whom the Software is
 # furnished to do so, subject to the following conditions:
-
+#
 # The above copyright notice and this permission notice shall be included in all
 # copies or substantial portions of the Software.
-
+#
 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
@@ -52,16 +52,16 @@ jobs:
 
     - name: Make simulation project
       run:
-        cd examples/01_hello_world/build_sim && cmake ../hw && make sim
+        cd examples/01_hello_world/build_sim && cmake -DFDEV_NAME=u55c ../hw && make sim
 
     - name: Make software project
       run:
-        cd examples/01_hello_world/build_sw && cmake ../sw -DSIM_DIR=../build_sim && make
+        cd examples/01_hello_world/build_sw && cmake ../sw -DEN_SIM=ON && make
 
     - name: Run simulation
-      run:
-        examples/01_hello_world/build_sw/bin/test -X 1024 -r 1 -s 0
-        examples/01_hello_world/build_sw/bin/test -X 1024 -r 1 -s 1
+      run: |
+        COYOTE_SIM_DIR=examples/01_hello_world/build_sim/ examples/01_hello_world/build_sw/test -X 1024 -r 1 -s 0
+        COYOTE_SIM_DIR=examples/01_hello_world/build_sim/ examples/01_hello_world/build_sw/test -X 1024 -r 1 -s 1
 
   run-02-hls-vadd:
     environment: fpga-synth
@@ -76,15 +76,15 @@ jobs:
 
     - name: Make simulation project
       run:
-        cd examples/02_hls_vadd/build_sim && cmake ../hw && make sim
+        cd examples/02_hls_vadd/build_sim && cmake -DFDEV_NAME=u55c ../hw && make sim
 
     - name: Make software project
       run:
-        cd examples/02_hls_vadd/build_sw && cmake ../sw -DSIM_DIR=../build_sim && make
+        cd examples/02_hls_vadd/build_sw && cmake ../sw -DEN_SIM=ON && make
 
     - name: Run simulation
-      run:
-        examples/02_hls_vadd/build_sw/bin/test
+      run: |
+        COYOTE_SIM_DIR=examples/02_hls_vadd/build_sim/ examples/02_hls_vadd/build_sw/test
 
   run-04-user-interrupts:
     environment: fpga-synth
@@ -99,15 +99,15 @@ jobs:
 
     - name: Make simulation project
       run:
-        cd examples/04_user_interrupts/build_sim && cmake ../hw && make sim
+        cd examples/04_user_interrupts/build_sim && cmake -DFDEV_NAME=u55c ../hw && make sim
 
     - name: Make software project
       run:
-        cd examples/04_user_interrupts/build_sw && cmake ../sw -DSIM_DIR=../build_sim && make
+        cd examples/04_user_interrupts/build_sw && cmake ../sw -DEN_SIM=ON && make
 
     - name: Run simulation
-      run:
-        examples/04_user_interrupts/build_sw/bin/test
+      run: |
+        COYOTE_SIM_DIR=examples/04_user_interrupts/build_sim/ examples/04_user_interrupts/build_sw/test
 
   run-07-perf-fpga:
     environment: fpga-synth
@@ -118,17 +118,17 @@ jobs:
 
     - name: Environment set-up
       run:
-        mkdir examples/07_perf_local/build_sim && mkdir examples/07_perf_local/build_sw && sudo apt-get install libboost-all-dev
+        mkdir examples/07_perf_fpga/build_sim && mkdir examples/07_perf_fpga/build_sw && sudo apt-get install libboost-all-dev
 
     - name: Make simulation project
       run:
-        cd examples/07_perf_local/build_sim && cmake ../hw && make sim
+        cd examples/07_perf_fpga/build_sim && cmake -DFDEV_NAME=u55c ../hw && make sim
 
     - name: Make software project
       run:
-        cd examples/07_perf_local/build_sw && cmake ../sw -DSIM_DIR=../build_sim && make
+        cd examples/07_perf_fpga/build_sw && cmake ../sw -DEN_SIM=ON && make
 
     - name: Run simulation
-      run:
-        examples/07_perf_local/build_sw/bin/test -X 1024 -r 1 -o 0
-        examples/07_perf_local/build_sw/bin/test -X 1024 -r 1 -o 1
+      run: |
+        COYOTE_SIM_DIR=examples/07_perf_fpga/build_sim/ examples/07_perf_fpga/build_sw/test -X 1024 -r 1 -o 0
+        COYOTE_SIM_DIR=examples/07_perf_fpga/build_sim/ examples/07_perf_fpga/build_sw/test -X 1024 -r 1 -o 1

cmake/FindCoyoteSW.cmake

@@ -24,161 +24,25 @@
 # SOFTWARE.
 ######################################################################################
 
-############################################
-#        COYOTE SOFTWARE PACKAGE           #
-############################################
-# @brief Set-up all the necessary libs, includes and source file compile the Coyote software
-
-cmake_minimum_required(VERSION 3.5)
-
-##############################
-#       USER OPTIONS        #
-#############################
-# Build with AVX support
-set(EN_AVX "1" CACHE STRING "AVX enabled.")
-
-# Build with support for ROCm (AMD GPUs)
-set(EN_GPU "0" CACHE STRING "AMD GPU enabled.")
-
-##############################
-#       BUILD CONFIG        #
-#############################
-set(CYT_LANG CXX)
-
-set(EN_SIM 0 CACHE STRING "Build for simulation.")
-set(SIM_DIR "" CACHE STRING "Directory that contains simulation project.")
-string(COMPARE EQUAL "${SIM_DIR}" "" result)
-if(NOT result)
-    set(EN_SIM 1)
-endif()
-
-# Find GPU libraries
-if(EN_GPU)
-    if(NOT DEFINED ROCM_PATH)
-    if(DEFINED ENV{ROCM_PATH})
-        set(ROCM_PATH $ENV{ROCM_PATH} CACHE PATH "Path to which ROCM has been installed")
-    elseif(DEFINED ENV{HIP_PATH})
-        set(ROCM_PATH "$ENV{HIP_PATH}/.." CACHE PATH "Path to which ROCM has been installed")
-    else()
-        set(ROCM_PATH "/opt/rocm" CACHE PATH "Path to which ROCM has been installed")
-    endif()
-    endif()
-
-    file(STRINGS "${ROCM_PATH}/.info/version" ROCM_VERSION)
-    message("-- Found ROCm: ${ROCM_VERSION}")
-
-    if (NOT DEFINED CMAKE_CXX_COMPILER)
-        set(CMAKE_CXX_COMPILER ${ROCM_PATH}/bin/hipcc)
-    endif()
-
-    if(NOT DEFINED HIP_PATH)
-        if(NOT DEFINED ENV{HIP_PATH})
-            set(HIP_PATH "/opt/rocm/hip" CACHE PATH "Path to which HIP has been installed")
-        else()
-            set(HIP_PATH $ENV{HIP_PATH} CACHE PATH "Path to which HIP has been installed")
-        endif()
-    endif()
-
-    if(NOT DEFINED HCC_PATH)
-        if(DEFINED ENV{HCC_PATH})
-            set(HCC_PATH $ENV{HCC_PATH} CACHE PATH "Path to which HCC has been installed")
-        else()
-            set(HCC_PATH "${ROCM_PATH}/hcc" CACHE PATH "Path to which HCC has been installed")
-        endif()
-        set(HCC_HOME "${HCC_PATH}")
-    endif()
-
-    if(NOT DEFINED HIP_CLANG_PATH)
-        if(NOT DEFINED ENV{HIP_CLANG_PATH})
-            set(HIP_CLANG_PATH "${ROCM_PATH}/llvm/bin" CACHE PATH "Path to which HIP compatible clang binaries have been installed")
-        else()
-            set(HIP_CLANG_PATH $ENV{HIP_CLANG_PATH} CACHE PATH "Path to which HIP compatible clang binaries have been installed")
-        endif()
-    endif()
-
-    set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${HIP_PATH}/cmake" )
-    list(APPEND CMAKE_PREFIX_PATH
-        "${HIP_PATH}/lib/cmake"
-        "${HIP_PATH}/../lib/cmake"
-    )
-
-    find_package(HIP QUIET)
-    if(HIP_FOUND)
-        message(STATUS "Found HIP: " ${HIP_VERSION})
-    else()
-        message(FATAL_ERROR "Could not find HIP. Ensure that HIP is either installed in /opt/rocm/hip or the variable HIP_PATH is set to point to the right location.")
-    endif()
-    find_package(hip REQUIRED)
-
-    set(CYT_LANG ${CYT_LANG} HIP)
-endif()
-
-# Create a Coyote lib
-project(
-    Coyote
-    VERSION 2.0.0
-    DESCRIPTION "Coyote library"
-    LANGUAGES ${CYT_LANG}
+message(WARNING "FindCoyoteSW is deprecated. Instead, you can choose one of two options:\n"
+  "1. If you're including Coyote as a git submodule, you can use the add_subdirectory(...)"
+  " directive in CMake. As an example, the following snippet of FindCoyoteSW:\n"
+  "     set(CYT_DIR \$\{CMAKE_SOURCE_DIR\}/../coyote)\n"
+  "     set(CMAKE_MODULE_PATH \$\{CMAKE_MODULE_PATH\} \$\{CYT_DIR\}/cmake)\n"
+  "     find_package(CoyoteSW REQUIRED)\n"
+  "can be replaced with:\n"
+  "     add_subdirectory(../coyote/sw coyote)\n"
+  "Please refer to the add_subdirectory documentation for more details.\n"
+  "2. If you're integrating Coyote into third-party software, it's likely that dependencies"
+  " are managed out-of-tree, and thus submodules are not used. In that case, you can install"
+  " coyote as a system library (by building the CMake project in sw/ and running `make install`)"
+  " and use CMake's find_package functionality as follows:"
+  "\n"
+  "       find_package(Coyote REQUIRED)\n"
+  "In both cases, you can then link Coyote into your project using:"
+  "\n"
+  "       target_link_libraries(<project> PRIVATE Coyote)\n"
+  "       target_include_directories(<project> PRIVATE \$\{COYOTE_INCLUDE_DIRS\})\n"
 )
-set(CMAKE_DEBUG_POSTFIX d)
-
-# Specify C++ standard, compile time options
-set(CMAKE_CXX_STANDARD 17)
-set(CMAKE_CXX_STANDARD_REQUIRED True)
-set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pthread -march=native -O3")
-
-# Source files, includes
-file(GLOB CYT_SOURCES CONFIGURE_DEPENDS "${CMAKE_CURRENT_LIST_DIR}/../sw/src/*.cpp")
-if(EN_SIM)
-    list(FILTER CYT_SOURCES EXCLUDE REGEX ".*cThread\\.cpp$")
-    file(GLOB SIM_SOURCES "${CMAKE_CURRENT_LIST_DIR}/../sim/sw/src/*.cpp")
-    list(APPEND CYT_SOURCES ${SIM_SOURCES})
-endif()
-add_library(Coyote SHARED ${CYT_SOURCES})
-
-# Output directories
-if (NOT CMAKE_LIBRARY_OUTPUT_DIRECTORY)
-    set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/lib")
-endif()
-
-if (NOT CMAKE_RUNTIME_OUTPUT_DIRECTORY)
-    set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/bin")
-endif()
-
-# Header includes
-set(CYT_INCLUDE_PATH ${CMAKE_CURRENT_LIST_DIR}/../sw/include)
-if(EN_SIM)
-    list(APPEND CYT_INCLUDE_PATH ${CMAKE_CURRENT_LIST_DIR}/../sim/sw/include)
-endif()
-target_include_directories(Coyote PUBLIC ${CYT_INCLUDE_PATH})
-target_link_directories(Coyote PUBLIC /usr/local/lib)
-
-# Additional libraries
-find_package(Boost COMPONENTS program_options REQUIRED)
-target_link_libraries(Coyote PUBLIC ${Boost_LIBRARIES})
-
-# Additional flags, depending on AVX or GPU support
-if(EN_AVX)
-    target_compile_definitions(Coyote PUBLIC EN_AVX)
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -mavx")
-endif()
-
-if(EN_GPU)
-    target_compile_definitions(Coyote PUBLIC EN_GPU)
-
-    # Include GPU directories
-    target_include_directories(Coyote
-            PUBLIC
-                $<BUILD_INTERFACE:${ROCM_PATH}/include>
-                $<BUILD_INTERFACE:${ROCM_PATH}/include/hsa>
-    )
-
-    # Add GPU libraries
-    target_link_libraries(Coyote PUBLIC hip::device numa pthread drm drm_amdgpu rt dl hsa-runtime64 hsakmt)
-
-endif()
-if (EN_SIM)
-    target_compile_definitions(Coyote PUBLIC SIM_DIR="${SIM_DIR}")
-endif()
-
 
+add_subdirectory(${CYT_DIR}/sw)

docs/source/intro/quick-start.rst

@@ -335,13 +335,23 @@ For some ideas of projects that were based on Coyote, check out the :ref:`public
 Simulating vFPGAs
 -----------------------
 A more comprehensive documentation for the simulation environment can be found at ``sim/README.md``.
-To get started with the simulation target for the software library, execute ``make sim`` after initializing the hardware build directory with ``cmake`` and add the SIM_DIR flag to the ``cmake`` call of the software build directory:
+To get started with the simulation target for the software library, execute ``make sim`` after initializing the hardware build directory with ``cmake``.
+To include and use the simulation software library, youh should change your CMake
+`add_subdirectory` or `find_package`:
 
-.. code-block:: bash
+.. code-block:: cmake
 
-    cmake <CMakeLists.txt_location> -DSIM_DIR=<sim_build_dir>...
+    add_subdirectory(path/to/coyote/sim/sw coyote) # Changed from add_subdirectory(path/to/coyote/sw coyote)
+    # or
+    find_package(CoyoteSimulation) # Changed from find_package(Coyote)
 
 After building the software with ``make``, the binary may be executed the same as if a programmed FPGA was available.
+You must point the program to the ``build_hw`` directory where you ran ``make sim`` via the ``COYOTE_SIM_DIR`` environment variable.
+For example, if our project builds a ``test`` executable, you should run it as:
+
+.. code-block:: bash
+   COYOTE_SIM_DIR=path/to/build_hw test <args...>
+
 It will automatically start Vivado in the background and start the testbench environment to simulate the vFPGA.
 
 Besides this simulation target for the Coyote C++ library, a Python unit test framework is available that is documented in detail in ``sim/unit-test/README.md``.

examples/01_hello_world/sw/CMakeLists.txt

@@ -30,17 +30,26 @@
 cmake_minimum_required(VERSION 3.5)
 project(example_01_hello_world)
 
-set(CYT_DIR ${CMAKE_SOURCE_DIR}/../../../)
-set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${CYT_DIR}/cmake)
-find_package(CoyoteSW REQUIRED)
+if(NOT CMAKE_BUILD_TYPE)
+    set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE)
+endif()
 
-message("*** Coyote Example 1: Hello World! [Software] ***")
+option(EN_SIM "Enable simulation mode for Coyote" OFF)
+
+if(EN_SIM)
+    add_subdirectory(../../../sim/sw ${CMAKE_BINARY_DIR}/coyote)
+else()
+    add_subdirectory(../../../sw ${CMAKE_BINARY_DIR}/coyote)
+endif()
 
 # Directory containing the executable(s) to be compiled
 set(TARGET_DIR "${CMAKE_SOURCE_DIR}/src/")
 
 # Create build targets and link against required libraries
 set(EXEC test)
 add_executable(${EXEC} ${TARGET_DIR}/main.cpp)
+
 target_link_libraries(${EXEC} PUBLIC Coyote)
-target_link_directories(${EXEC} PUBLIC /usr/local/lib)
+
+find_package(Boost REQUIRED COMPONENTS program_options)
+target_link_libraries(${EXEC} PUBLIC Boost::program_options)

examples/01_hello_world/sw/src/main.cpp

@@ -31,8 +31,8 @@
 #include <boost/program_options.hpp>
 
 // Coyote-specific includes
-#include "cBench.hpp"
-#include "cThread.hpp"
+#include <coyote/cBench.hpp>
+#include <coyote/cThread.hpp>
 
 // Constants
 #define N_LATENCY_REPS 1

examples/02_hls_vadd/sw/CMakeLists.txt

@@ -28,9 +28,17 @@
 cmake_minimum_required(VERSION 3.5)
 project(example_02_hls_vadd)
 
-set(CYT_DIR ${CMAKE_SOURCE_DIR}/../../../)
-set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${CYT_DIR}/cmake)
-find_package(CoyoteSW REQUIRED)
+if(NOT CMAKE_BUILD_TYPE)
+    set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE)
+endif()
+
+option(EN_SIM "Enable simulation mode for Coyote" OFF)
+
+if(EN_SIM)
+    add_subdirectory(../../../sim/sw ${CMAKE_BINARY_DIR}/coyote)
+else()
+    add_subdirectory(../../../sw ${CMAKE_BINARY_DIR}/coyote)
+endif()
 
 message("*** Coyote Example 2: HLS Vector Addition [Software] ***")
 
@@ -40,5 +48,8 @@ set(TARGET_DIR "${CMAKE_SOURCE_DIR}/src/")
 # Create build targets and link against required libraries
 set(EXEC test)
 add_executable(${EXEC} ${TARGET_DIR}/main.cpp)
+
 target_link_libraries(${EXEC} PUBLIC Coyote)
-target_link_directories(${EXEC} PUBLIC /usr/local/lib)
+
+find_package(Boost REQUIRED COMPONENTS program_options)
+target_link_libraries(${EXEC} PUBLIC Boost::program_options)

examples/02_hls_vadd/sw/src/main.cpp

@@ -31,7 +31,7 @@
 #include <boost/program_options.hpp>
 
 // Coyote-specific includes
-#include "cThread.hpp"
+#include <coyote/cThread.hpp>
 
 // Default vFPGA to assign cThreads to
 #define DEFAULT_VFPGA_ID 0