CIRCT  19.0.0git
Services.h
Go to the documentation of this file.
1 //===- StdServices.h - ESI standard services C++ API ------------*- 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 // The APIs in this backend are all optionally implemented. The lower level
10 // ones, however, are strongly recommended. 'Services' here refers to ESI
11 // services. These are standard APIs into the standard ESI services.
12 //
13 // DO NOT EDIT!
14 // This file is distributed as part of an ESI package. The source for this file
15 // should always be modified within CIRCT.
16 //
17 //===----------------------------------------------------------------------===//
18 
19 // NOLINTNEXTLINE(llvm-header-guard)
20 #ifndef ESI_RUNTIME_SERVICES_H
21 #define ESI_RUNTIME_SERVICES_H
22 
23 #include "esi/Common.h"
24 #include "esi/Ports.h"
25 
26 #include <cstdint>
27 
28 namespace esi {
29 class AcceleratorConnection;
30 namespace services {
31 
32 /// Add a custom interface to a service client at a particular point in the
33 /// design hierarchy.
34 class ServicePort : public BundlePort {
35 public:
37  virtual ~ServicePort() = default;
38 };
39 
40 /// Parent class of all APIs modeled as 'services'. May or may not map to a
41 /// hardware side 'service'.
42 class Service {
43 public:
44  using Type = const std::type_info &;
45  virtual ~Service() = default;
46 
47  virtual std::string getServiceSymbol() const = 0;
48 
49  /// Get specialized port for this service to attach to the given appid path.
50  /// Null returns mean nothing to attach.
51  virtual ServicePort *getPort(AppIDPath id, const BundleType *type,
52  const std::map<std::string, ChannelPort &> &,
53  AcceleratorConnection &) const {
54  return nullptr;
55  }
56 };
57 
58 /// A service for which there are no standard services registered. Requires
59 /// ports be added to the design hierarchy instead of high level interfaces like
60 /// the ones in StdServices.h.
61 class CustomService : public Service {
62 public:
63  CustomService(AppIDPath idPath, const ServiceImplDetails &details,
64  const HWClientDetails &clients);
65  virtual ~CustomService() = default;
66 
67  virtual std::string getServiceSymbol() const override {
68  return serviceSymbol;
69  }
70 
71 protected:
72  std::string serviceSymbol;
74 };
75 
76 /// Information about the Accelerator system.
77 class SysInfo : public Service {
78 public:
79  virtual ~SysInfo() = default;
80 
81  virtual std::string getServiceSymbol() const override;
82 
83  /// Get the ESI version number to check version compatibility.
84  virtual uint32_t getEsiVersion() const = 0;
85 
86  /// Return the JSON-formatted system manifest.
87  virtual std::string getJsonManifest() const;
88 
89  /// Return the zlib compressed JSON system manifest.
90  virtual std::vector<uint8_t> getCompressedManifest() const = 0;
91 };
92 
93 class MMIO : public Service {
94 public:
95  virtual ~MMIO() = default;
96  virtual uint64_t read(uint32_t addr) const = 0;
97  virtual void write(uint32_t addr, uint64_t data) = 0;
98  virtual std::string getServiceSymbol() const override;
99 };
100 
101 /// Implement the SysInfo API for a standard MMIO protocol.
102 class MMIOSysInfo final : public SysInfo {
103 public:
104  MMIOSysInfo(const MMIO *);
105 
106  /// Get the ESI version number to check version compatibility.
107  uint32_t getEsiVersion() const override;
108 
109  /// Return the zlib compressed JSON system manifest.
110  virtual std::vector<uint8_t> getCompressedManifest() const override;
111 
112 private:
113  const MMIO *mmio;
114 };
115 
116 /// Service for calling functions.
117 class FuncService : public Service {
118 public:
120  const std::string &implName, ServiceImplDetails details,
121  HWClientDetails clients);
122 
123  virtual std::string getServiceSymbol() const override;
124  virtual ServicePort *getPort(AppIDPath id, const BundleType *type,
125  const std::map<std::string, ChannelPort &> &,
126  AcceleratorConnection &) const override;
127 
128  /// A function call which gets attached to a service port.
129  class Function : public ServicePort {
130  friend class FuncService;
131  Function(AppID id, const std::map<std::string, ChannelPort &> &channels);
132 
133  public:
134  static Function *get(AppID id, WriteChannelPort &arg,
136 
137  void connect();
138  std::future<MessageData> call(const MessageData &arg);
139 
140  private:
141  std::mutex callMutex;
144  };
145 
146 private:
147  std::string symbol;
148 };
149 
150 /// Service for servicing function calls from the accelerator.
151 class CallService : public Service {
152 public:
153  CallService(AcceleratorConnection *acc, AppIDPath id, std::string implName,
154  ServiceImplDetails details, HWClientDetails clients);
155 
156  virtual std::string getServiceSymbol() const override;
157  virtual ServicePort *getPort(AppIDPath id, const BundleType *type,
158  const std::map<std::string, ChannelPort &> &,
159  AcceleratorConnection &) const override;
160 
161  /// A function call which gets attached to a service port.
162  class Callback : public ServicePort {
163  friend class CallService;
165  const std::map<std::string, ChannelPort &> &channels);
166 
167  public:
168  /// Connect a callback to code which will be executed when the accelerator
169  /// invokes the callback. The 'quick' flag indicates that the callback is
170  /// sufficiently fast that it could be called in the same thread as the
171  /// port callback.
172  void connect(std::function<MessageData(const MessageData &)> callback,
173  bool quick = false);
174 
175  private:
179  };
180 
181 private:
182  std::string symbol;
183 };
184 
185 /// Registry of services which can be instantiated directly by the Accelerator
186 /// class if the backend doesn't do anything special with a service.
188 public:
189  /// Create a service instance from the given details. Returns nullptr if
190  /// 'svcType' isn't registered.
192  Service::Type svcType, AppIDPath id,
193  std::string implName,
194  ServiceImplDetails details,
195  HWClientDetails clients);
196 
197  /// Resolve a service type from a string. If the string isn't recognized,
198  /// default to CustomService.
199  static Service::Type lookupServiceType(const std::string &);
200 };
201 
202 } // namespace services
203 } // namespace esi
204 
205 #endif // ESI_RUNTIME_SERVICES_H
Abstract class representing a connection to an accelerator.
Definition: Accelerator.h:78
Services provide connections to 'bundles' – collections of named, unidirectional communication channe...
Definition: Ports.h:137
std::map< std::string, ChannelPort & > channels
Definition: Ports.h:173
BundlePort(AppID id, std::map< std::string, ChannelPort & > channels)
Construct a port.
Definition: Ports.cpp:22
Bundles represent a collection of channels.
Definition: Types.h:44
A logical chunk of data representing serialized data.
Definition: Common.h:86
A ChannelPort which reads data from the accelerator.
Definition: Ports.h:64
A ChannelPort which sends data to the accelerator.
Definition: Ports.h:52
A function call which gets attached to a service port.
Definition: Services.h:162
Callback(AcceleratorConnection &acc, AppID id, const std::map< std::string, ChannelPort & > &channels)
Definition: Services.cpp:146
void connect(std::function< MessageData(const MessageData &)> callback, bool quick=false)
Connect a callback to code which will be executed when the accelerator invokes the callback.
Definition: Services.cpp:157
AcceleratorConnection & acc
Definition: Services.h:178
Service for servicing function calls from the accelerator.
Definition: Services.h:151
CallService(AcceleratorConnection *acc, AppIDPath id, std::string implName, ServiceImplDetails details, HWClientDetails clients)
Definition: Services.cpp:129
virtual std::string getServiceSymbol() const override
Definition: Services.cpp:137
virtual ServicePort * getPort(AppIDPath id, const BundleType *type, const std::map< std::string, ChannelPort & > &, AcceleratorConnection &) const override
Get specialized port for this service to attach to the given appid path.
Definition: Services.cpp:140
A service for which there are no standard services registered.
Definition: Services.h:61
CustomService(AppIDPath idPath, const ServiceImplDetails &details, const HWClientDetails &clients)
Definition: Services.cpp:75
virtual ~CustomService()=default
virtual std::string getServiceSymbol() const override
Definition: Services.h:67
A function call which gets attached to a service port.
Definition: Services.h:129
std::future< MessageData > call(const MessageData &arg)
Definition: Services.cpp:123
static Function * get(AppID id, WriteChannelPort &arg, ReadChannelPort &result)
Definition: Services.cpp:111
Function(AppID id, const std::map< std::string, ChannelPort & > &channels)
Definition: Services.cpp:103
Service for calling functions.
Definition: Services.h:117
virtual std::string getServiceSymbol() const override
Definition: Services.cpp:94
virtual ServicePort * getPort(AppIDPath id, const BundleType *type, const std::map< std::string, ChannelPort & > &, AcceleratorConnection &) const override
Get specialized port for this service to attach to the given appid path.
Definition: Services.cpp:97
FuncService(AcceleratorConnection *acc, AppIDPath id, const std::string &implName, ServiceImplDetails details, HWClientDetails clients)
Definition: Services.cpp:86
Implement the SysInfo API for a standard MMIO protocol.
Definition: Services.h:102
virtual std::vector< uint8_t > getCompressedManifest() const override
Return the zlib compressed JSON system manifest.
Definition: Services.cpp:55
uint32_t getEsiVersion() const override
Get the ESI version number to check version compatibility.
Definition: Services.cpp:48
MMIOSysInfo(const MMIO *)
Definition: Services.cpp:46
virtual uint64_t read(uint32_t addr) const =0
virtual ~MMIO()=default
virtual void write(uint32_t addr, uint64_t data)=0
virtual std::string getServiceSymbol() const override
Definition: Services.cpp:44
Add a custom interface to a service client at a particular point in the design hierarchy.
Definition: Services.h:34
virtual ~ServicePort()=default
Registry of services which can be instantiated directly by the Accelerator class if the backend doesn...
Definition: Services.h:187
static Service::Type lookupServiceType(const std::string &)
Resolve a service type from a string.
Definition: Services.cpp:192
static Service * createService(AcceleratorConnection *acc, Service::Type svcType, AppIDPath id, std::string implName, ServiceImplDetails details, HWClientDetails clients)
Create a service instance from the given details.
Definition: Services.cpp:179
Parent class of all APIs modeled as 'services'.
Definition: Services.h:42
virtual std::string getServiceSymbol() const =0
const std::type_info & Type
Definition: Services.h:44
virtual ~Service()=default
virtual ServicePort * getPort(AppIDPath id, const BundleType *type, const std::map< std::string, ChannelPort & > &, AcceleratorConnection &) const
Get specialized port for this service to attach to the given appid path.
Definition: Services.h:51
Information about the Accelerator system.
Definition: Services.h:77
virtual std::string getJsonManifest() const
Return the JSON-formatted system manifest.
Definition: Services.cpp:32
virtual uint32_t getEsiVersion() const =0
Get the ESI version number to check version compatibility.
virtual std::vector< uint8_t > getCompressedManifest() const =0
Return the zlib compressed JSON system manifest.
virtual std::string getServiceSymbol() const override
Definition: Services.cpp:27
virtual ~SysInfo()=default
Definition: esi.py:1
std::map< std::string, std::any > ServiceImplDetails
Definition: Common.h:81
std::vector< HWClientDetail > HWClientDetails
Definition: Common.h:80