Place the public API in a special place with a canonical way of acces…

…sing them (#322)

### Issue
Solving part of #324

### Description
It's currently unclear which files consist of UMD's public API and which
are private headers.
Additionally, consumers like tt-metal are reaching around with arbitrary
paths to fetch headers. They shouldn't.
There should be one place for the public API and one way for consumers
to access it, and private stuff should remain private.

### List of the changes
* Place all UMD Device's public API under `api/umd/device/`
* Expose `api/` as the include dir, so all consumers must use
`umd/device/foo.h` to include API headers
    * Even internal to UMD::Device, though this is subjective.
* Do not expose any other directory publicly
* Inside Device we may include other headers, but external consumers
cannot.

### Testing
Corresponding PR in tt-metal to consume with the new paths: 

### API Changes
(When making API changes, don't merge this PR until tt_metal and
tt_debuda PRs are approved.)
(Then merge this PR, change the client PRs to point to UMD main, and
then merge them.)

(Remove following lines if untrue) This PR has API changes:
- [x] (If breaking change) tt_metal approved PR pointing to this branch:
tenstorrent/tt-metal#15322
- [x] (If breaking change) tt_debuda approved PR pointing to this
branch: tenstorrent/tt-lens#193

CMakeLists.txt

@@ -53,6 +53,7 @@ message(STATUS "UMD build type: ${CMAKE_BUILD_TYPE}")
 
 include(dependencies)
 
+add_subdirectory(common)
 add_subdirectory(device)
 add_subdirectory(src)
 

common/CMakeLists.txt

@@ -0,0 +1,13 @@
+add_library(umd_common INTERFACE)
+add_library(${PROJECT_NAME}::Common ALIAS umd_common)
+
+target_sources(
+    umd_common
+    INTERFACE
+        assert.hpp
+        backtrace.hpp
+        gtest_initializer.hpp # FIXME: this should be tucked away with the tests
+        logger.hpp
+)
+
+target_include_directories(umd_common INTERFACE .)

common/assert.hpp

@@ -13,7 +13,7 @@
 #include <sstream>
 #include <vector>
 
-#include "common/logger.hpp"
+#include "logger.hpp"
 
 namespace tt {
 template <typename A, typename B>

common/logger.hpp

@@ -20,7 +20,7 @@
 #include <pybind11/iostream.h>
 #endif
 
-#include "common/backtrace.hpp"
+#include "backtrace.hpp"
 #include "fmt/color.h"
 #include "fmt/core.h"
 #include "fmt/ostream.h"

common/utils.hpp

@@ -18,10 +18,10 @@ std::string get_abs_path(std::string path) {
     std::filesystem::path current_file_path = std::filesystem::path(__FILE__);
     std::filesystem::path umd_root;
     if (current_file_path.is_absolute()) {
-        umd_root = current_file_path.parent_path().parent_path();
+        umd_root = current_file_path.parent_path().parent_path().parent_path();
     } else {
         std::filesystem::path umd_root_relative =
-            std::filesystem::relative(std::filesystem::path(__FILE__).parent_path().parent_path(), "../");
+            std::filesystem::relative(std::filesystem::path(__FILE__).parent_path().parent_path().parent_path(), "../");
         umd_root = std::filesystem::canonical(umd_root_relative);
     }
     std::filesystem::path abs_path = umd_root / path;

device/CMakeLists.txt

@@ -2,41 +2,41 @@ set(POSITION_INDEPENDENT_CODE ON)
 
 generate_fbs_header(${PROJECT_SOURCE_DIR}/device/simulation/tt_simulation_device.fbs)
 
-set(UMD_DEVICE_SRCS
-    architecture_implementation.cpp
-    cpuset_lib.cpp
-    tlb.cpp
-    tt_cluster_descriptor.cpp
-    cluster.cpp
-    tt_silicon_driver_common.cpp
-    tt_soc_descriptor.cpp
-    xy_pair.cpp
-    simulation/tt_simulation_device.cpp
-    simulation/tt_simulation_host.cpp
-    blackhole/blackhole_implementation.cpp
-    grayskull/grayskull_implementation.cpp
-    wormhole/wormhole_implementation.cpp
-    coordinate_manager.cpp
-    blackhole/blackhole_coordinate_manager.cpp
-    wormhole/wormhole_coordinate_manager.cpp
-    pcie/pci_device.cpp
-    hugepage.cpp
-)
-
-add_library(device SHARED ${UMD_DEVICE_SRCS})
+add_library(device SHARED)
 add_library(${PROJECT_NAME}::device ALIAS device)
-add_library(${PROJECT_NAME}_device ALIAS device) # For legacy I guess
 
-target_sources(device PRIVATE ${FBS_GENERATED_HEADER})
+target_sources(
+    device
+    PRIVATE
+        architecture_implementation.cpp
+        blackhole/blackhole_coordinate_manager.cpp
+        blackhole/blackhole_implementation.cpp
+        cluster.cpp
+        coordinate_manager.cpp
+        cpuset_lib.cpp
+        grayskull/grayskull_implementation.cpp
+        hugepage.cpp
+        pcie/pci_device.cpp
+        simulation/tt_simulation_device.cpp
+        simulation/tt_simulation_host.cpp
+        tlb.cpp
+        tt_cluster_descriptor.cpp
+        tt_silicon_driver_common.cpp
+        tt_soc_descriptor.cpp
+        wormhole/wormhole_coordinate_manager.cpp
+        wormhole/wormhole_implementation.cpp
+        xy_pair.cpp
+        ${FBS_GENERATED_HEADER}
+)
 
 target_include_directories(
     device
     PUBLIC
-        $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}>
-        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/api>
         $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}/${PROJECT_NAME}>
         $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}/${PROJECT_NAME}/device>
     PRIVATE
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
         $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>
 )
 
@@ -49,6 +49,8 @@ target_link_libraries(
         flatbuffers
         uv
     PRIVATE
+        umd::Common
+        umd::Firmware
         hwloc
         rt
         Boost::interprocess

device/architecture_implementation.h → device/api/umd/device/architecture_implementation.h

@@ -11,9 +11,9 @@
 #include <tuple>
 #include <vector>
 
-#include "device/tlb.h"
-#include "device/tt_arch_types.h"
-#include "device/xy_pair.h"
+#include "umd/device/tlb.h"
+#include "umd/device/tt_arch_types.h"
+#include "umd/device/xy_pair.h"
 
 struct tt_driver_host_address_params;
 struct tt_driver_eth_interface_params;

device/blackhole/blackhole_implementation.h → device/api/umd/device/blackhole_implementation.h

@@ -9,8 +9,8 @@
 #include <array>
 #include <stdexcept>
 
-#include "device/architecture_implementation.h"
-#include "device/tlb.h"
+#include "umd/device/architecture_implementation.h"
+#include "umd/device/tlb.h"
 
 namespace tt::umd {
 

device/cluster.h → device/api/umd/device/cluster.h

@@ -13,14 +13,14 @@
 #include <unordered_set>
 #include <vector>
 
-#include "device/tlb.h"
-#include "device/tt_cluster_descriptor_types.h"
-#include "device/tt_io.hpp"
 #include "fmt/core.h"
-#include "pcie/pci_device.hpp"
 #include "tt_silicon_driver_common.hpp"
 #include "tt_soc_descriptor.h"
 #include "tt_xy_pair.h"
+#include "umd/device/pci_device.hpp"
+#include "umd/device/tlb.h"
+#include "umd/device/tt_cluster_descriptor_types.h"
+#include "umd/device/tt_io.hpp"
 
 using TLB_DATA = tt::umd::tlb_data;
 

device/coordinate_manager.h → device/api/umd/device/coordinate_manager.h

@@ -10,8 +10,8 @@
 #include <set>
 #include <vector>
 
-#include "device/tt_arch_types.h"
-#include "device/tt_xy_pair.h"
+#include "umd/device/tt_arch_types.h"
+#include "umd/device/tt_xy_pair.h"
 
 class CoordinateManager {
 public:

device/device_api_metal.h → device/api/umd/device/device_api_metal.h

@@ -5,5 +5,5 @@
  */
 
 #pragma once
-#include "device/cluster.h"
-#include "device/driver_atomics.h"
+#include "umd/device/cluster.h"
+#include "umd/device/driver_atomics.h"

device/grayskull/grayskull_implementation.h → device/api/umd/device/grayskull_implementation.h

@@ -8,8 +8,8 @@
 
 #include <array>
 
-#include "device/architecture_implementation.h"
-#include "device/tlb.h"
+#include "architecture_implementation.h"
+#include "umd/device/tlb.h"
 
 namespace tt::umd {
 

device/hugepage.h → device/api/umd/device/hugepage.h

@@ -9,7 +9,7 @@
 #include <cstdint>
 #include <string>
 
-#include "device/tt_cluster_descriptor_types.h"
+#include "umd/device/tt_cluster_descriptor_types.h"
 
 namespace tt::umd {
 

device/pcie/pci_device.hpp → device/api/umd/device/pci_device.hpp

@@ -12,12 +12,12 @@
 #include <unordered_map>
 #include <vector>
 
-#include "common/semver.hpp"
-#include "device/tlb.h"
-#include "device/tt_arch_types.h"
-#include "device/tt_cluster_descriptor_types.h"
-#include "device/tt_xy_pair.h"
 #include "fmt/format.h"
+#include "umd/device/semver.hpp"
+#include "umd/device/tlb.h"
+#include "umd/device/tt_arch_types.h"
+#include "umd/device/tt_cluster_descriptor_types.h"
+#include "umd/device/tt_xy_pair.h"
 
 // TODO: this is used up in cluster.cpp but that logic ought to be
 // lowered into the PCIDevice class since it is specific to PCIe cards.

device/tt_cluster_descriptor.h → device/api/umd/device/tt_cluster_descriptor.h

@@ -16,9 +16,9 @@
 #include <unordered_set>
 #include <vector>
 
-#include "device/tt_cluster_descriptor_types.h"
-#include "device/tt_xy_pair.h"
-#include "tt_arch_types.h"
+#include "umd/device/tt_arch_types.h"
+#include "umd/device/tt_cluster_descriptor_types.h"
+#include "umd/device/tt_xy_pair.h"
 
 namespace YAML {
 class Node;

device/simulation/tt_simulation_device.h → device/api/umd/device/tt_simulation_device.h

@@ -10,8 +10,8 @@
 #include <fstream>
 #include <vector>
 
-#include "device/cluster.h"
-#include "device/simulation/tt_simulation_host.hpp"
+#include "umd/device/cluster.h"
+#include "umd/device/tt_simulation_host.hpp"
 
 class tt_SimulationDevice : public tt_device {
 public:

device/simulation/tt_simulation_host.hpp → device/api/umd/device/tt_simulation_host.hpp

@@ -5,7 +5,7 @@
 #include <memory>
 #include <vector>
 
-#include "device/tt_xy_pair.h"
+#include "umd/device/tt_xy_pair.h"
 
 #define NNG_SOCKET_PREFIX "ipc:///tmp/"
 

device/tt_soc_descriptor.h → device/api/umd/device/tt_soc_descriptor.h

@@ -14,10 +14,11 @@
 #include <unordered_map>
 #include <vector>
 
-#include "device/coordinate_manager.h"
-#include "device/tt_arch_types.h"
 #include "fmt/core.h"
 #include "tt_xy_pair.h"
+#include "umd/device/coordinate_manager.h"
+#include "umd/device/tt_arch_types.h"
+#include "umd/device/tt_xy_pair.h"
 
 namespace YAML {
 class Node;

device/tt_xy_pair.h → device/api/umd/device/tt_xy_pair.h

@@ -8,7 +8,7 @@
 
 #include <regex>
 
-#include "device/xy_pair.h"
+#include "umd/device/xy_pair.h"
 
 using tt_xy_pair = tt::umd::xy_pair;
 using tt_cxy_pair = tt::umd::cxy_pair;

device/wormhole/wormhole_implementation.h → device/api/umd/device/wormhole_implementation.h

@@ -8,8 +8,8 @@
 
 #include <array>
 
-#include "device/architecture_implementation.h"
-#include "device/tlb.h"
+#include "architecture_implementation.h"
+#include "umd/device/tlb.h"
 
 namespace tt::umd {
 

device/architecture_implementation.cpp

@@ -2,11 +2,11 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
-#include "device/architecture_implementation.h"
+#include "umd/device/architecture_implementation.h"
 
-#include "device/blackhole/blackhole_implementation.h"
-#include "device/grayskull/grayskull_implementation.h"
-#include "device/wormhole/wormhole_implementation.h"
+#include "umd/device/blackhole_implementation.h"
+#include "umd/device/grayskull_implementation.h"
+#include "umd/device/wormhole_implementation.h"
 
 namespace tt::umd {
 

device/blackhole/blackhole_coordinate_manager.h

@@ -6,7 +6,7 @@
 
 #pragma once
 
-#include "device/coordinate_manager.h"
+#include "umd/device/coordinate_manager.h"
 
 class BlackholeCoordinateManager : public CoordinateManager {
 public:

device/blackhole/blackhole_implementation.cpp

@@ -2,11 +2,11 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
-#include "blackhole_implementation.h"
+#include "umd/device/blackhole_implementation.h"
 
-#include "device/cluster.h"
-#include "src/firmware/riscv/blackhole/eth_interface.h"
-#include "src/firmware/riscv/blackhole/host_mem_address_map.h"
+#include "blackhole/eth_interface.h"
+#include "blackhole/host_mem_address_map.h"
+#include "umd/device/cluster.h"
 
 constexpr std::uint32_t NOC_ADDR_LOCAL_BITS = 36;   // source: noc_parameters.h, common for WH && BH
 constexpr std::uint32_t NOC_ADDR_NODE_ID_BITS = 6;  // source: noc_parameters.h, common for WH && BH

device/cluster.cpp

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: (c) 2023 Tenstorrent Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-#include "cluster.h"
+#include "umd/device/cluster.h"
 
 #include <assert.h>
 #include <dirent.h>
@@ -36,15 +36,13 @@
 #include <utility>
 #include <vector>
 
-#include "common/logger.hpp"
-#include "device/architecture_implementation.h"
-#include "device/driver_atomics.h"
-#include "device/hugepage.h"
-#include "device/tlb.h"
-#include "device/tt_arch_types.h"
-#include "device/tt_cluster_descriptor.h"
-#include "tt_arch_types.h"
-#include "tt_cluster_descriptor.h"
+#include "logger.hpp"
+#include "umd/device/architecture_implementation.h"
+#include "umd/device/driver_atomics.h"
+#include "umd/device/hugepage.h"
+#include "umd/device/tlb.h"
+#include "umd/device/tt_arch_types.h"
+#include "umd/device/tt_cluster_descriptor.h"
 #include "yaml-cpp/yaml.h"
 
 using namespace boost::interprocess;
@@ -119,8 +117,8 @@ const tt_SocDescriptor& tt_device::get_soc_descriptor(chip_id_t chip_id) const {
 #include <iomanip>
 #include <thread>
 
-#include "tt_silicon_driver_common.hpp"
-#include "tt_xy_pair.h"
+#include "umd/device/tt_silicon_driver_common.hpp"
+#include "umd/device/tt_xy_pair.h"
 
 struct routing_cmd_t {
     uint64_t sys_addr;