CIRCT 21.0.0git
Loading...
Searching...
No Matches
Engines.h
Go to the documentation of this file.
1//===- Engines.h - Implement port communication -----------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// DO NOT EDIT!
10// This file is distributed as part of an ESI package. The source for this file
11// should always be modified within CIRCT.
12//
13//===----------------------------------------------------------------------===//
14//
15// Engines (as in DMA engine) implement the actual communication between the
16// host and the accelerator. They are low level of the ESI runtime API and are
17// not intended to be used directly by users.
18//
19// They are called "engines" rather than "DMA engines" since communication need
20// not be implemented via DMA.
21//
22//===----------------------------------------------------------------------===//
23
24// NOLINTNEXTLINE(llvm-header-guard)
25#ifndef ESI_ENGINGES_H
26#define ESI_ENGINGES_H
27
28#include "esi/Common.h"
29#include "esi/Ports.h"
30#include "esi/Services.h"
31#include "esi/Utils.h"
32
33#include <cassert>
34#include <future>
35
36namespace esi {
37class Accelerator;
38
39/// Engines implement the actual channel communication between the host and the
40/// accelerator. Engines can support multiple channels. They are low level of
41/// the ESI runtime API and are not intended to be used directly by users.
42class Engine {
43public:
45 virtual ~Engine() = default;
46 /// Start the engine, if applicable.
47 virtual void connect() { connected = true; };
48 /// Stop the engine, if applicable.
49 virtual void disconnect() { connected = false; };
50 /// Get a port for a channel, from the cache if it exists or create it. An
51 /// engine may override this method if different behavior is desired.
52 virtual ChannelPort &requestPort(AppIDPath idPath,
53 const std::string &channelName,
54 BundleType::Direction dir, const Type *type);
55
56protected:
57 /// Each engine needs to know how to create a ports. This method is called if
58 /// a port doesn't exist in the engine cache.
59 virtual std::unique_ptr<ChannelPort>
60 createPort(AppIDPath idPath, const std::string &channelName,
61 BundleType::Direction dir, const Type *type) = 0;
62
65
66private:
67 std::map<std::pair<AppIDPath, std::string>, std::unique_ptr<ChannelPort>>
69};
70
71/// Since engines can support multiple channels BUT not necessarily all of the
72/// channels in a bundle, a mapping from bundle channels to engines is needed.
75
76public:
77 /// Request ports for all the channels in a bundle. If the engine doesn't
78 /// exist for a particular channel, skip said channel.
79 PortMap requestPorts(const AppIDPath &idPath,
80 const BundleType *bundleType) const;
81
82private:
83 /// Set a particlar engine for a particular channel. Should only be called by
84 /// AcceleratorConnection while registering engines.
85 void setEngine(const std::string &channelName, Engine *engine);
86 std::map<std::string, Engine *> bundleEngineMap;
87};
88
89namespace registry {
90
91/// Create an engine by name. This is the primary way to create engines for
92/// "normal" backends.
93std::unique_ptr<Engine> createEngine(AcceleratorConnection &conn,
94 const std::string &dmaEngineName,
95 AppIDPath idPath,
96 const ServiceImplDetails &details,
97 const HWClientDetails &clients);
98
99namespace internal {
100
101/// Engines can register themselves for pluggable functionality.
102using EngineCreate = std::function<std::unique_ptr<Engine>(
103 AcceleratorConnection &conn, AppIDPath idPath,
104 const ServiceImplDetails &details, const HWClientDetails &clients)>;
105void registerEngine(const std::string &name, EngineCreate create);
106
107/// Helper struct to register engines.
108template <typename TEngine>
110 RegisterEngine(const char *name) { registerEngine(name, &TEngine::create); }
111};
112
113#define CONCAT_(prefix, suffix) prefix##suffix
114#define CONCAT(prefix, suffix) CONCAT_(prefix, suffix)
115#define REGISTER_ENGINE(Name, TEngine) \
116 static ::esi::registry::internal::RegisterEngine<TEngine> CONCAT( \
117 __register_engine__, __LINE__)(Name)
118
119} // namespace internal
120} // namespace registry
121
122} // namespace esi
123
124#endif // ESI_PORTS_H
Abstract class representing a connection to an accelerator.
Definition Accelerator.h:79
Since engines can support multiple channels BUT not necessarily all of the channels in a bundle,...
Definition Engines.h:73
PortMap requestPorts(const AppIDPath &idPath, const BundleType *bundleType) const
Request ports for all the channels in a bundle.
Definition Engines.cpp:424
std::map< std::string, Engine * > bundleEngineMap
Definition Engines.h:86
void setEngine(const std::string &channelName, Engine *engine)
Set a particlar engine for a particular channel.
Definition Engines.cpp:438
Bundles represent a collection of channels.
Definition Types.h:44
Unidirectional channels are the basic communication primitive between the host and accelerator.
Definition Ports.h:36
Engines implement the actual channel communication between the host and the accelerator.
Definition Engines.h:42
bool connected
Definition Engines.h:63
virtual void connect()
Start the engine, if applicable.
Definition Engines.h:47
virtual ChannelPort & requestPort(AppIDPath idPath, const std::string &channelName, BundleType::Direction dir, const Type *type)
Get a port for a channel, from the cache if it exists or create it.
Definition Engines.cpp:411
virtual std::unique_ptr< ChannelPort > createPort(AppIDPath idPath, const std::string &channelName, BundleType::Direction dir, const Type *type)=0
Each engine needs to know how to create a ports.
virtual ~Engine()=default
virtual void disconnect()
Stop the engine, if applicable.
Definition Engines.h:49
Engine(AcceleratorConnection &conn)
Definition Engines.h:44
AcceleratorConnection & conn
Definition Engines.h:64
std::map< std::pair< AppIDPath, std::string >, std::unique_ptr< ChannelPort > > ownedPorts
Definition Engines.h:68
Root class of the ESI type system.
Definition Types.h:27
std::function< std::unique_ptr< Engine >(AcceleratorConnection &conn, AppIDPath idPath, const ServiceImplDetails &details, const HWClientDetails &clients)> EngineCreate
Engines can register themselves for pluggable functionality.
Definition Engines.h:104
void registerEngine(const std::string &name, EngineCreate create)
Definition Engines.cpp:474
std::unique_ptr< Engine > createEngine(AcceleratorConnection &conn, const std::string &dmaEngineName, AppIDPath idPath, const ServiceImplDetails &details, const HWClientDetails &clients)
Create an engine by name.
Definition Engines.cpp:463
Definition esi.py:1
std::map< std::string, std::any > ServiceImplDetails
Definition Common.h:98
std::map< std::string, ChannelPort & > PortMap
Definition Ports.h:29
std::vector< HWClientDetail > HWClientDetails
Definition Common.h:97
Helper struct to register engines.
Definition Engines.h:109