test_utils.cpp

Go to the documentation of this file.

//===- test_utils.cpp ----------------------------000---*- C++ -*-===//
//
// Copyright (C) 2024 Advanced Micro Devices, Inc.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
 
// This file contains common helper functions for the generic host code
 
#include "test_utils.h"
#include <cassert>
#include <filesystem>
 
#ifdef TEST_UTILS_USE_XRT
#include "xrt/xrt_device.h"
#include "xrt/xrt_kernel.h"
#endif
 
// --------------------------------------------------------------------------
// Command Line Argument Handling
// --------------------------------------------------------------------------
 
void test_utils::check_arg_file_exists(const cxxopts::ParseResult &result,
                                       std::string name) {
  if (!result.count(name)) {
    throw std::runtime_error("Missing required argument: " + name);
  }
  std::string path = result[name].as<std::string>();
  if (!std::filesystem::exists(path)) {
    throw std::runtime_error("File does not exist: " + path);
  }
}
 
void test_utils::add_default_options(cxxopts::Options &options) {
  options.add_options()("help,h", "produce help message")(
      "xclbin,x", "the input xclbin path", cxxopts::value<std::string>())(
      "kernel,k", "the kernel name in the XCLBIN (for instance PP_PRE_FD)",
      cxxopts::value<std::string>())("verbosity,v",
                                     "the verbosity of the output",
                                     cxxopts::value<int>()->default_value("0"))(
      "instr,i",
      "path of file containing userspace instructions sent to the NPU",
      cxxopts::value<std::string>())(
      "verify", "whether to verify the AIE computed output",
      cxxopts::value<bool>()->default_value("true"))(
      "iters", "number of iterations",
      cxxopts::value<int>()->default_value("1"))(
      "warmup", "number of warmup iterations",
      cxxopts::value<int>()->default_value("0"))(
      "trace_sz,t", "trace size", cxxopts::value<int>()->default_value("0"))(
      "trace_file", "where to store trace output",
      cxxopts::value<std::string>()->default_value("trace.txt"));
}
 
void test_utils::parse_options(int argc, const char *argv[],
                               cxxopts::Options &options,
                               cxxopts::ParseResult &vm) {
  try {
    vm = options.parse(argc, argv);
 
    if (vm.count("help")) {
      std::cout << options.help() << "\n";
      std::exit(1);
    }
  } catch (const cxxopts::exceptions::parsing &e) {
    std::cerr << e.what() << "\n\n";
    std::cerr << "Usage:\n" << options.help() << "\n";
    std::exit(1);
  }
 
  try {
    check_arg_file_exists(vm, "xclbin");
    check_arg_file_exists(vm, "instr");
  } catch (const std::exception &ex) {
    std::cerr << ex.what() << "\n\n";
  }
}
 
// --------------------------------------------------------------------------
// AIE Specifics
// --------------------------------------------------------------------------
 
std::vector<uint32_t> test_utils::load_instr_sequence(std::string instr_path) {
  std::ifstream instr_file(instr_path);
  std::string line;
  std::vector<uint32_t> instr_v;
  while (std::getline(instr_file, line)) {
    std::istringstream iss(line);
    uint32_t a;
    if (!(iss >> std::hex >> a)) {
      throw std::runtime_error("Unable to parse instruction file\n");
    }
    instr_v.push_back(a);
  }
  return instr_v;
}
 
std::vector<uint32_t> test_utils::load_instr_binary(std::string instr_path) {
  // Open file in binary mode
  std::ifstream instr_file(instr_path, std::ios::binary);
  if (!instr_file.is_open()) {
    throw std::runtime_error("Unable to open instruction file\n");
  }
 
  // Get the size of the file
  instr_file.seekg(0, std::ios::end);
  std::streamsize size = instr_file.tellg();
  instr_file.seekg(0, std::ios::beg);
 
  // Check that the file size is a multiple of 4 bytes (size of uint32_t)
  if (size % 4 != 0) {
    throw std::runtime_error("File size is not a multiple of 4 bytes\n");
  }
 
  // Allocate vector and read the binary data
  std::vector<uint32_t> instr_v(size / 4);
  if (!instr_file.read(reinterpret_cast<char *>(instr_v.data()), size)) {
    throw std::runtime_error("Failed to read instruction file\n");
  }
  return instr_v;
}
 
#ifdef TEST_UTILS_USE_XRT
 
// --------------------------------------------------------------------------
// XRT
// --------------------------------------------------------------------------
std::string test_utils::get_kernel_name(const xrt::xclbin &xclbin,
                                        const std::string &name_prefix,
                                        int verbosity) {
  std::string available;
  for (auto &k : xclbin.get_kernels()) {
    auto name = k.get_name();
    if (verbosity >= 1)
      std::cout << "Name: " << name << std::endl;
    if (name.rfind(name_prefix, 0) == 0)
      return name;
    if (!available.empty())
      available += ", ";
    available += name;
  }
  throw std::runtime_error(
      "No kernel in the xclbin starts with '" + name_prefix +
      "'. Available kernels: " + (available.empty() ? "(none)" : available));
}
 
void test_utils::init_xrt_load_kernel(xrt::device &device, xrt::kernel &kernel,
                                      int verbosity, std::string xclbinFileName,
                                      std::string kernelNameInXclbin) {
  // Get a device handle
  unsigned int device_index = 0;
  device = xrt::device(device_index);
 
  // Load the xclbin
  if (verbosity >= 1)
    std::cout << "Loading xclbin: " << xclbinFileName << "\n";
  auto xclbin = xrt::xclbin(xclbinFileName);
 
  if (verbosity >= 1)
    std::cout << "Kernel opcode: " << kernelNameInXclbin << "\n";
 
  // Get the kernel from the xclbin
  auto kernelName = get_kernel_name(xclbin, kernelNameInXclbin, verbosity);
 
  // Register xclbin
  if (verbosity >= 1)
    std::cout << "Registering xclbin: " << xclbinFileName << "\n";
 
  device.register_xclbin(xclbin);
 
  // Get a hardware context
  if (verbosity >= 1)
    std::cout << "Getting hardware context.\n";
  xrt::hw_context context(device, xclbin.get_uuid());
 
  // Get a kernel handle
  if (verbosity >= 1)
    std::cout << "Getting handle to kernel:" << kernelName << "\n";
  kernel = xrt::kernel(context, kernelName);
 
  return;
}
 
#endif // TEST_UTILS_USE_XRT
 
// --------------------------------------------------------------------------
// Matrix / Float / Math
// --------------------------------------------------------------------------
 
// nearly_equal function adapted from Stack Overflow, License CC BY-SA 4.0
// Original author: P-Gn
// Source: https://stackoverflow.com/a/32334103
bool test_utils::nearly_equal(float a, float b, float epsilon, float abs_th)
// those defaults are arbitrary and could be removed
{
  assert(std::numeric_limits<float>::epsilon() <= epsilon);
  assert(epsilon < 1.f);
 
  if (a == b)
    return true;
 
  auto diff = std::abs(a - b);
  auto norm =
      std::min((std::abs(a) + std::abs(b)), std::numeric_limits<float>::max());
  // or even faster: std::min(std::abs(a + b),
  // std::numeric_limits<float>::max()); keeping this commented out until I
  // update figures below
  return diff < std::max(abs_th, epsilon * norm);
}
 
// --------------------------------------------------------------------------
// Tracing
// --------------------------------------------------------------------------
void test_utils::write_out_trace(char *traceOutPtr, size_t trace_size,
                                 std::string path) {
  std::ofstream fout(path);
  uint32_t *traceOut = (uint32_t *)traceOutPtr;
  for (int i = 0; i < trace_size / sizeof(traceOut[0]); i++) {
    fout << std::setfill('0') << std::setw(8) << std::hex << (int)traceOut[i];
    fout << std::endl;
  }
}