Accelerator.h

Go to the documentation of this file.

//===- Accelerator.h - Base ESI runtime API ---------------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
//
// Basic ESI APIs. The 'Accelerator' class is the superclass for all accelerator
// backends. It should (usually) provide enough functionality such that users do
// not have to interact with the platform-specific backend implementation with
// the exception of connecting to the accelerator.
//
// DO NOT EDIT!
// This file is distributed as part of an ESI package. The source for this file
// should always be modified within CIRCT.
//
//===----------------------------------------------------------------------===//
 
// NOLINTNEXTLINE(llvm-header-guard)
#ifndef ESI_ACCELERATOR_H
#define ESI_ACCELERATOR_H
 
#include "esi/Context.h"
#include "esi/Design.h"
#include "esi/Engines.h"
#include "esi/Manifest.h"
#include "esi/Ports.h"
#include "esi/Services.h"
 
#include <atomic>
#include <functional>
#include <future>
#include <map>
#include <memory>
#include <mutex>
#include <string>
#include <thread>
#include <tuple>
#include <typeinfo>
#include <utility>
#include <vector>
 
namespace esi {
// Forward declarations.
class AcceleratorServiceThread;
 
//===----------------------------------------------------------------------===//
// Metadata constants which may or may not be used by various backends. Provided
// here since they are intended to be somewhat standard.
//===----------------------------------------------------------------------===//
 
constexpr uint32_t MetadataOffset = 8;
 
constexpr uint64_t MagicNumberLo = 0xE5100E51;
constexpr uint64_t MagicNumberHi = 0x207D98E5;
constexpr uint64_t MagicNumber = MagicNumberLo | (MagicNumberHi << 32);
constexpr uint64_t MagicNumberOffset = 0;
 
/// Keep in sync with circt::esi::esiApiVersion and the PyCDE BSP.
constexpr uint32_t ExpectedVersionNumber = 1;
constexpr uint64_t VersionNumberOffset = 8;
 
constexpr uint32_t ManifestPtrOffset = 0x10;
 
constexpr uint32_t CycleCountOffset = 0x20;
constexpr uint32_t CoreFreqOffset = 0x28;
 
/// Magic value which, when written to MMIO offset `ResetRequestOffset`,
/// requests a design reset.  Keep in sync with 'ResetMagicNumber' in the PyCDE
/// BSP (python/esiaccel/bsp/common.py).
constexpr uint64_t ResetMagicNumber = 0x00000E510000B007;
/// Offset into the (global) MMIO space at which to request a design reset.
constexpr uint32_t ResetRequestOffset = 0x38;
 
//===----------------------------------------------------------------------===//
// Accelerator design hierarchy root.
//===----------------------------------------------------------------------===//
 
/// Top level accelerator class. Maintains a shared pointer to the manifest,
/// which owns objects used in the design hierarchy owned by this class. Since
/// this class owns the entire design hierarchy, when it gets destroyed the
/// entire design hierarchy gets destroyed so all of the instances, ports, etc.
/// are no longer valid pointers.
class Accelerator : public HWModule {
public:
  Accelerator() = delete;
  Accelerator(const Accelerator &) = delete;
  ~Accelerator() = default;
  Accelerator(std::optional<ModuleInfo> info,
              std::vector<std::unique_ptr<Instance>> children,
              std::vector<services::Service *> services,
              std::vector<std::unique_ptr<BundlePort>> &&ports)
      : HWModule(info, std::move(children), services, std::move(ports)) {}
};
 
//===----------------------------------------------------------------------===//
// Connection to the accelerator and its services.
//===----------------------------------------------------------------------===//
 
/// Abstract class representing a connection to an accelerator. Actual
/// connections (e.g. to a co-simulation or actual device) are implemented by
/// subclasses. No methods in here are thread safe.
class AcceleratorConnection {
public:
  AcceleratorConnection(Context &ctxt);
  virtual ~AcceleratorConnection();
  Context &getCtxt() const { return ctxt; }
  Logger &getLogger() const { return ctxt.getLogger(); }
 
  /// Disconnect from the accelerator cleanly. Drains owned engines before the
  /// accelerator is released. Backends _must_ call this from their destructor
  /// while still fully constructed (their vtable/resources alive), since engine
  /// teardown may reference accelerator-owned objects. Must be idempotent.
  virtual void disconnect();
 
  /// Request a reset of the accelerator design. Returns true if the reset was
  /// successfully requested, false if it could not be performed for any reason
  /// -- most commonly because the backend (BSP) does not support resets.
  virtual bool reset();
 
  /// Return a pointer to the accelerator 'service' thread (or threads). If the
  /// thread(s) are not running, they will be started when this method is
  /// called. `std::thread` is used. If users don't want the runtime to spin up
  /// threads, don't call this method. `AcceleratorServiceThread` is owned by
  /// AcceleratorConnection and governed by the lifetime of the this object.
  virtual AcceleratorServiceThread *getServiceThread();
 
  using Service = services::Service;
  /// Get a typed reference to a particular service type. Caller does *not* take
  /// ownership of the returned pointer -- the Accelerator object owns it.
  /// Pointer lifetime ends with the Accelerator lifetime.
  template <typename ServiceClass>
  ServiceClass *getService(AppIDPath id = {}, std::string implName = {},
                           ServiceImplDetails details = {},
                           HWClientDetails clients = {}) {
    return dynamic_cast<ServiceClass *>(
        getService(typeid(ServiceClass), id, implName, details, clients));
  }
  /// Calls `createService` and caches the result. Subclasses can override if
  /// they want to use their own caching mechanism.
  virtual Service *getService(Service::Type service, AppIDPath id = {},
                              std::string implName = {},
                              ServiceImplDetails details = {},
                              HWClientDetails clients = {});
 
  /// Assume ownership of an accelerator object. Ties the lifetime of the
  /// accelerator to this connection. Returns a raw pointer to the object.
  Accelerator *takeOwnership(std::unique_ptr<Accelerator> accel);
 
  /// Create a new engine for channel communication with the accelerator. The
  /// default is to call the global `createEngine` to get an engine which has
  /// registered itself. Individual accelerator connection backends can override
  /// this to customize behavior.
  virtual void createEngine(const std::string &engineTypeName, AppIDPath idPath,
                            const ServiceImplDetails &details,
                            const HWClientDetails &clients);
  virtual const BundleEngineMap &getEngineMapFor(AppIDPath id) {
    return clientEngines[id];
  }
 
  Accelerator &getAccelerator() {
    if (!ownedAccelerator)
      throw std::runtime_error(
          "AcceleratorConnection does not own an accelerator");
    return *ownedAccelerator;
  }
 
protected:
  /// If `createEngine` is overridden, this method should be called to register
  /// the engine and all of the channels it services.
  void registerEngine(AppIDPath idPath, std::unique_ptr<Engine> engine,
                      const HWClientDetails &clients);
 
  /// Drop accelerator-owned objects before a derived backend destroys resources
  /// that those objects may reference.
  void clearOwnedObjects();
 
  /// Called by `getServiceImpl` exclusively. It wraps the pointer returned by
  /// this in a unique_ptr and caches it. Separate this from the
  /// wrapping/caching since wrapping/caching is an implementation detail.
  virtual Service *createService(Service::Type service, AppIDPath idPath,
                                 std::string implName,
                                 const ServiceImplDetails &details,
                                 const HWClientDetails &clients) = 0;
 
  /// Collection of owned engines.
  std::map<AppIDPath, std::unique_ptr<Engine>> ownedEngines;
  /// Mapping of clients to their servicing engines.
  std::map<AppIDPath, BundleEngineMap> clientEngines;
 
private:
  /// ESI accelerator context.
  Context &ctxt;
 
  /// Cache services via a unique_ptr so they get free'd automatically when
  /// Accelerator objects get deconstructed.
  using ServiceCacheKey = std::tuple<std::string, AppIDPath>;
  std::map<ServiceCacheKey, std::unique_ptr<Service>> serviceCache;
 
  std::unique_ptr<AcceleratorServiceThread> serviceThread;
 
  /// Accelerator object owned by this connection.
  std::unique_ptr<Accelerator> ownedAccelerator;
};
 
namespace registry {
 
namespace internal {
 
/// Backends can register themselves to be connected via a connection string.
using BackendCreate = std::function<std::unique_ptr<AcceleratorConnection>(
    Context &, std::string)>;
void registerBackend(const std::string &name, BackendCreate create);
 
// Helper struct to
template <typename TAccelerator>
struct RegisterAccelerator {
  RegisterAccelerator(const char *name) {
    registerBackend(name, &TAccelerator::connect);
  }
};
 
#define REGISTER_ACCELERATOR(Name, TAccelerator)                               \
  static ::esi::registry::internal::RegisterAccelerator<TAccelerator>          \
  __register_accel____LINE__(Name)
 
} // namespace internal
} // namespace registry
 
/// Background thread which services various requests. Currently, it listens on
/// ports and calls callbacks for incoming messages on said ports.
///
/// All methods are virtual so that users may provide their own service thread
/// implementation. Overriders can reuse the default implementation piecemeal by
/// invoking the base-class methods -- typically overriding `poll()` (to change
/// what a single iteration does) or `loop()` (to change how iterations are
/// scheduled). Subclasses that need to run their own `loop()` from the outset
/// should use the protected `DeferStart` constructor to prevent the base class
/// from starting the thread, then call `start()` themselves.
class AcceleratorServiceThread {
public:
  AcceleratorServiceThread();
  virtual ~AcceleratorServiceThread();
 
  /// When there's data on any of the listenPorts, call the callback. Callable
  /// from any thread.
  virtual void
  addListener(std::initializer_list<ReadChannelPort *> listenPorts,
              std::function<void(ReadChannelPort *, MessageData)> callback);
 
  /// Poll this module.
  virtual void addPoll(HWModule &module);
 
  /// Add a task to be invoked on every service iteration. Callable from any
  /// thread.
  virtual void addTask(std::function<void(void)> task);
 
  /// Instruct the service thread to stop running.
  virtual void stop();
 
protected:
  /// Tag type used to construct the base class without starting the service
  /// thread. Intended for subclasses that need to run their own loop from the
  /// start.
  struct DeferStart {};
  explicit AcceleratorServiceThread(DeferStart);
 
  /// Start the service thread. Called by the default constructor. Spawns a
  /// std::thread which invokes `loop()` via virtual dispatch.
  virtual void start();
 
  /// The main service loop. Runs until `shutdown` is set to true. The default
  /// implementation yields and then calls `poll()` on every iteration.
  virtual void loop();
 
  /// Perform a single iteration of servicing: drain any ready listener
  /// futures, invoke their callbacks, and run all registered tasks.
  /// Overriders can invoke this from a custom loop to reuse the default
  /// servicing behavior.
  virtual void poll();
 
  /// Set to true to request the service loop to exit.
  std::atomic<bool> shutdown{false};
  /// The thread running `loop()`.
  std::thread me;
 
  /// Protects `listeners` and `taskList`.
  std::mutex m;
 
  /// Map of read ports to callbacks and their in-flight async reads.
  std::map<ReadChannelPort *,
           std::pair<std::function<void(ReadChannelPort *, MessageData)>,
                     std::future<MessageData>>>
      listeners;
 
  /// Tasks which should be called on every loop iteration.
  std::vector<std::function<void(void)>> taskList;
};
} // namespace esi
 
#endif // ESI_ACCELERATOR_H