Loading [MathJax]/extensions/tex2jax.js
CIRCT 22.0.0git
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
esiCppAccel.cpp
Go to the documentation of this file.
1//===- esiaccel.cpp - ESI runtime python bindings ---------------*- 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// Simply wrap the C++ API into a Python module called 'esiaccel'.
10//
11//===----------------------------------------------------------------------===//
12
13#include "esi/Accelerator.h"
14#include "esi/Services.h"
15
16#include "esi/backends/Cosim.h"
17
18#include <ranges>
19#include <sstream>
20
21// pybind11 includes
22#include <pybind11/pybind11.h>
23namespace py = pybind11;
24
25#include <pybind11/functional.h>
26#include <pybind11/stl.h>
27
28using namespace esi;
29using namespace esi::services;
30
31namespace pybind11 {
32/// Pybind11 needs a little help downcasting with non-bound instances.
33template <>
34struct polymorphic_type_hook<ChannelPort> {
35 static const void *get(const ChannelPort *port, const std::type_info *&type) {
36 if (auto p = dynamic_cast<const WriteChannelPort *>(port)) {
37 type = &typeid(WriteChannelPort);
38 return p;
39 }
40 if (auto p = dynamic_cast<const ReadChannelPort *>(port)) {
41 type = &typeid(ReadChannelPort);
42 return p;
43 }
44 return port;
45 }
46};
47template <>
48struct polymorphic_type_hook<Service> {
49 static const void *get(const Service *svc, const std::type_info *&type) {
50 if (auto p = dynamic_cast<const MMIO *>(svc)) {
51 type = &typeid(MMIO);
52 return p;
53 }
54 if (auto p = dynamic_cast<const SysInfo *>(svc)) {
55 type = &typeid(SysInfo);
56 return p;
57 }
58 if (auto p = dynamic_cast<const HostMem *>(svc)) {
59 type = &typeid(HostMem);
60 return p;
61 }
62 if (auto p = dynamic_cast<const TelemetryService *>(svc)) {
63 type = &typeid(TelemetryService);
64 return p;
65 }
66 return svc;
67 }
68};
69
70namespace detail {
71/// Pybind11 doesn't have a built-in type caster for std::any
72/// (https://github.com/pybind/pybind11/issues/1590). We must provide one which
73/// knows about all of the potential types which the any might be.
74template <>
75struct type_caster<std::any> {
76public:
77 PYBIND11_TYPE_CASTER(std::any, const_name("object"));
78
79 static handle cast(std::any src, return_value_policy /* policy */,
80 handle /* parent */) {
81 const std::type_info &t = src.type();
82 if (t == typeid(std::string))
83 return py::str(std::any_cast<std::string>(src));
84 else if (t == typeid(int64_t))
85 return py::int_(std::any_cast<int64_t>(src));
86 else if (t == typeid(uint64_t))
87 return py::int_(std::any_cast<uint64_t>(src));
88 else if (t == typeid(double))
89 return py::float_(std::any_cast<double>(src));
90 else if (t == typeid(bool))
91 return py::bool_(std::any_cast<bool>(src));
92 else if (t == typeid(std::nullptr_t))
93 return py::none();
94 return py::none();
95 }
96};
97} // namespace detail
98} // namespace pybind11
99
100/// Resolve a Type to the Python wrapper object.
101py::object getPyType(std::optional<const Type *> t) {
102 py::object typesModule = py::module_::import("esiaccel.types");
103 if (!t)
104 return py::none();
105 return typesModule.attr("_get_esi_type")(*t);
106}
107
108// NOLINTNEXTLINE(readability-identifier-naming)
109PYBIND11_MODULE(esiCppAccel, m) {
110 py::class_<Type>(m, "Type")
111 .def(py::init<const Type::ID &>(), py::arg("id"))
112 .def_property_readonly("id", &Type::getID)
113 .def("__repr__", [](Type &t) { return "<" + t.getID() + ">"; });
114 py::class_<ChannelType, Type>(m, "ChannelType")
115 .def(py::init<const Type::ID &, const Type *>(), py::arg("id"),
116 py::arg("inner"))
117 .def_property_readonly("inner", &ChannelType::getInner,
118 py::return_value_policy::reference);
119 py::enum_<BundleType::Direction>(m, "Direction")
120 .value("To", BundleType::Direction::To)
121 .value("From", BundleType::Direction::From)
122 .export_values();
123 py::class_<BundleType, Type>(m, "BundleType")
124 .def(py::init<const Type::ID &, const BundleType::ChannelVector &>(),
125 py::arg("id"), py::arg("channels"))
126 .def_property_readonly("channels", &BundleType::getChannels,
127 py::return_value_policy::reference);
128 py::class_<VoidType, Type>(m, "VoidType")
129 .def(py::init<const Type::ID &>(), py::arg("id"));
130 py::class_<AnyType, Type>(m, "AnyType")
131 .def(py::init<const Type::ID &>(), py::arg("id"));
132 py::class_<BitVectorType, Type>(m, "BitVectorType")
133 .def(py::init<const Type::ID &, uint64_t>(), py::arg("id"),
134 py::arg("width"))
135 .def_property_readonly("width", &BitVectorType::getWidth);
136 py::class_<BitsType, BitVectorType>(m, "BitsType")
137 .def(py::init<const Type::ID &, uint64_t>(), py::arg("id"),
138 py::arg("width"));
139 py::class_<IntegerType, BitVectorType>(m, "IntegerType")
140 .def(py::init<const Type::ID &, uint64_t>(), py::arg("id"),
141 py::arg("width"));
142 py::class_<SIntType, IntegerType>(m, "SIntType")
143 .def(py::init<const Type::ID &, uint64_t>(), py::arg("id"),
144 py::arg("width"));
145 py::class_<UIntType, IntegerType>(m, "UIntType")
146 .def(py::init<const Type::ID &, uint64_t>(), py::arg("id"),
147 py::arg("width"));
148 py::class_<StructType, Type>(m, "StructType")
149 .def(py::init<const Type::ID &, const StructType::FieldVector &>(),
150 py::arg("id"), py::arg("fields"))
151 .def_property_readonly("fields", &StructType::getFields,
152 py::return_value_policy::reference);
153 py::class_<ArrayType, Type>(m, "ArrayType")
154 .def(py::init<const Type::ID &, const Type *, uint64_t>(), py::arg("id"),
155 py::arg("element_type"), py::arg("size"))
156 .def_property_readonly("element", &ArrayType::getElementType,
157 py::return_value_policy::reference)
158 .def_property_readonly("size", &ArrayType::getSize);
159
160 py::class_<Constant>(m, "Constant")
161 .def_property_readonly("value", [](Constant &c) { return c.value; })
162 .def_property_readonly(
163 "type", [](Constant &c) { return getPyType(*c.type); },
164 py::return_value_policy::reference);
165
166 py::class_<AppID>(m, "AppID")
167 .def(py::init<std::string, std::optional<uint32_t>>(), py::arg("name"),
168 py::arg("idx") = std::nullopt)
169 .def_property_readonly("name", [](AppID &id) { return id.name; })
170 .def_property_readonly("idx",
171 [](AppID &id) -> py::object {
172 if (id.idx)
173 return py::cast(id.idx);
174 return py::none();
175 })
176 .def("__repr__",
177 [](AppID &id) {
178 std::string ret = "<" + id.name;
179 if (id.idx)
180 ret = ret + "[" + std::to_string(*id.idx) + "]";
181 ret = ret + ">";
182 return ret;
183 })
184 .def("__eq__", [](AppID &a, AppID &b) { return a == b; })
185 .def("__hash__", [](AppID &id) {
186 return utils::hash_combine(std::hash<std::string>{}(id.name),
187 std::hash<uint32_t>{}(id.idx.value_or(-1)));
188 });
189 py::class_<AppIDPath>(m, "AppIDPath").def("__repr__", &AppIDPath::toStr);
190
191 py::class_<ModuleInfo>(m, "ModuleInfo")
192 .def_property_readonly("name", [](ModuleInfo &info) { return info.name; })
193 .def_property_readonly("summary",
194 [](ModuleInfo &info) { return info.summary; })
195 .def_property_readonly("version",
196 [](ModuleInfo &info) { return info.version; })
197 .def_property_readonly("repo", [](ModuleInfo &info) { return info.repo; })
198 .def_property_readonly("commit_hash",
199 [](ModuleInfo &info) { return info.commitHash; })
200 .def_property_readonly("constants",
201 [](ModuleInfo &info) { return info.constants; })
202 // TODO: "extra" field.
203 .def("__repr__", [](ModuleInfo &info) {
204 std::string ret;
205 std::stringstream os(ret);
206 os << info;
207 return os.str();
208 });
209
210 py::enum_<Logger::Level>(m, "LogLevel")
211 .value("Debug", Logger::Level::Debug)
212 .value("Info", Logger::Level::Info)
213 .value("Warning", Logger::Level::Warning)
214 .value("Error", Logger::Level::Error)
215 .export_values();
216 py::class_<Logger>(m, "Logger");
217
218 py::class_<services::Service>(m, "Service");
219
220 py::class_<SysInfo, services::Service>(m, "SysInfo")
221 .def("esi_version", &SysInfo::getEsiVersion)
222 .def("json_manifest", &SysInfo::getJsonManifest);
223
224 py::class_<MMIO::RegionDescriptor>(m, "MMIORegionDescriptor")
225 .def_property_readonly("base",
226 [](MMIO::RegionDescriptor &r) { return r.base; })
227 .def_property_readonly("size",
228 [](MMIO::RegionDescriptor &r) { return r.size; });
229 py::class_<services::MMIO, services::Service>(m, "MMIO")
230 .def("read", &services::MMIO::read)
231 .def("write", &services::MMIO::write)
232 .def_property_readonly("regions", &services::MMIO::getRegions,
233 py::return_value_policy::reference);
234
235 py::class_<services::HostMem::HostMemRegion>(m, "HostMemRegion")
236 .def_property_readonly("ptr",
238 return reinterpret_cast<uintptr_t>(mem.getPtr());
239 })
240 .def_property_readonly("size",
242
243 py::class_<services::HostMem::Options>(m, "HostMemOptions")
244 .def(py::init<>())
245 .def_readwrite("writeable", &services::HostMem::Options::writeable)
246 .def_readwrite("use_large_pages",
248 .def("__repr__", [](services::HostMem::Options &opts) {
249 std::string ret = "HostMemOptions(";
250 if (opts.writeable)
251 ret += "writeable ";
252 if (opts.useLargePages)
253 ret += "use_large_pages";
254 ret += ")";
255 return ret;
256 });
257
258 py::class_<services::HostMem, services::Service>(m, "HostMem")
259 .def("allocate", &services::HostMem::allocate, py::arg("size"),
260 py::arg("options") = services::HostMem::Options(),
261 py::return_value_policy::take_ownership)
262 .def(
263 "map_memory",
264 [](HostMem &self, uintptr_t ptr, size_t size, HostMem::Options opts) {
265 return self.mapMemory(reinterpret_cast<void *>(ptr), size, opts);
266 },
267 py::arg("ptr"), py::arg("size"),
268 py::arg("options") = services::HostMem::Options())
269 .def(
270 "unmap_memory",
271 [](HostMem &self, uintptr_t ptr) {
272 return self.unmapMemory(reinterpret_cast<void *>(ptr));
273 },
274 py::arg("ptr"));
275
276 // py::class_<std::__basic_future<MessageData>>(m, "MessageDataFuture");
277 py::class_<std::future<MessageData>>(m, "MessageDataFuture")
278 .def("valid",
279 [](std::future<MessageData> &f) {
280 // For some reason, if we just pass the function pointer, pybind11
281 // sees `std::__basic_future` as the type and pybind11_stubgen
282 // emits an error.
283 return f.valid();
284 })
285 .def("wait",
286 [](std::future<MessageData> &f) {
287 // Yield the GIL while waiting for the future to complete, in case
288 // of python callbacks occuring from other threads while waiting.
289 py::gil_scoped_release release{};
290 f.wait();
291 })
292 .def("get", [](std::future<MessageData> &f) {
293 std::optional<MessageData> data;
294 {
295 // Yield the GIL while waiting for the future to complete, in case of
296 // python callbacks occuring from other threads while waiting.
297 py::gil_scoped_release release{};
298 data.emplace(f.get());
299 }
300 return py::bytearray((const char *)data->getBytes(), data->getSize());
301 });
302
303 py::class_<ChannelPort>(m, "ChannelPort")
304 .def("connect", &ChannelPort::connect,
305 py::arg("buffer_size") = std::nullopt)
306 .def("disconnect", &ChannelPort::disconnect)
307 .def_property_readonly("type", &ChannelPort::getType,
308 py::return_value_policy::reference);
309
310 py::class_<WriteChannelPort, ChannelPort>(m, "WriteChannelPort")
311 .def("write",
312 [](WriteChannelPort &p, py::bytearray &data) {
313 py::buffer_info info(py::buffer(data).request());
314 std::vector<uint8_t> dataVec((uint8_t *)info.ptr,
315 (uint8_t *)info.ptr + info.size);
316 p.write(dataVec);
317 })
318 .def("tryWrite", [](WriteChannelPort &p, py::bytearray &data) {
319 py::buffer_info info(py::buffer(data).request());
320 std::vector<uint8_t> dataVec((uint8_t *)info.ptr,
321 (uint8_t *)info.ptr + info.size);
322 return p.tryWrite(dataVec);
323 });
324 py::class_<ReadChannelPort, ChannelPort>(m, "ReadChannelPort")
325 .def(
326 "read",
327 [](ReadChannelPort &p) -> py::bytearray {
328 MessageData data;
329 p.read(data);
330 return py::bytearray((const char *)data.getBytes(), data.getSize());
331 },
332 "Read data from the channel. Blocking.")
333 .def("read_async", &ReadChannelPort::readAsync);
334
335 py::class_<BundlePort>(m, "BundlePort")
336 .def_property_readonly("id", &BundlePort::getID)
337 .def_property_readonly("channels", &BundlePort::getChannels,
338 py::return_value_policy::reference)
339 .def("getWrite", &BundlePort::getRawWrite,
340 py::return_value_policy::reference)
341 .def("getRead", &BundlePort::getRawRead,
342 py::return_value_policy::reference);
343
344 py::class_<ServicePort, BundlePort>(m, "ServicePort");
345
346 py::class_<MMIO::MMIORegion, ServicePort>(m, "MMIORegion")
347 .def_property_readonly("descriptor", &MMIO::MMIORegion::getDescriptor)
348 .def("read", &MMIO::MMIORegion::read)
349 .def("write", &MMIO::MMIORegion::write);
350
351 py::class_<FuncService::Function, ServicePort>(m, "Function")
352 .def(
353 "call",
354 [](FuncService::Function &self,
355 py::bytearray msg) -> std::future<MessageData> {
356 py::buffer_info info(py::buffer(msg).request());
357 std::vector<uint8_t> dataVec((uint8_t *)info.ptr,
358 (uint8_t *)info.ptr + info.size);
359 MessageData data(dataVec);
360 return self.call(data);
361 },
362 py::return_value_policy::take_ownership)
363 .def("connect", &FuncService::Function::connect);
364
365 py::class_<CallService::Callback, ServicePort>(m, "Callback")
366 .def("connect", [](CallService::Callback &self,
367 std::function<py::object(py::object)> pyCallback) {
368 // TODO: Under certain conditions this will cause python to crash. I
369 // don't remember how to replicate these crashes, but IIRC they are
370 // deterministic.
371 self.connect([pyCallback](const MessageData &req) -> MessageData {
372 py::gil_scoped_acquire acquire{};
373 std::vector<uint8_t> arg(req.getBytes(),
374 req.getBytes() + req.getSize());
375 py::bytearray argObj((const char *)arg.data(), arg.size());
376 auto ret = pyCallback(argObj);
377 if (ret.is_none())
378 return MessageData();
379 py::buffer_info info(py::buffer(ret).request());
380 std::vector<uint8_t> dataVec((uint8_t *)info.ptr,
381 (uint8_t *)info.ptr + info.size);
382 return MessageData(dataVec);
383 });
384 });
385
386 py::class_<TelemetryService::Telemetry, ServicePort>(m, "Telemetry")
389
390 // Store this variable (not commonly done) as the "children" method needs for
391 // "Instance" to be defined first.
392 auto hwmodule =
393 py::class_<HWModule>(m, "HWModule")
394 .def_property_readonly("info", &HWModule::getInfo)
395 .def_property_readonly("ports", &HWModule::getPorts,
396 py::return_value_policy::reference)
397 .def_property_readonly("services", &HWModule::getServices,
398 py::return_value_policy::reference);
399
400 // In order to inherit methods from "HWModule", it needs to be defined first.
401 py::class_<Instance, HWModule>(m, "Instance")
402 .def_property_readonly("id", &Instance::getID);
403
404 py::class_<Accelerator, HWModule>(m, "Accelerator");
405
406 // Since this returns a vector of Instance*, we need to define Instance first
407 // or else pybind11-stubgen complains.
408 hwmodule.def_property_readonly("children", &HWModule::getChildren,
409 py::return_value_policy::reference);
410
411 auto accConn = py::class_<AcceleratorConnection>(m, "AcceleratorConnection");
412
413 py::class_<Context>(m, "Context")
414 .def(py::init<>())
415 .def("connect", &Context::connect)
416 .def("set_stdio_logger", [](Context &ctxt, Logger::Level level) {
417 ctxt.setLogger(std::make_unique<StreamLogger>(level));
418 });
419
420 accConn.def(py::init(&registry::connect))
421 .def(
422 "sysinfo",
423 [](AcceleratorConnection &acc) {
424 return acc.getService<services::SysInfo>({});
425 },
426 py::return_value_policy::reference)
427 .def(
428 "get_service_mmio",
429 [](AcceleratorConnection &acc) {
430 return acc.getService<services::MMIO>({});
431 },
432 py::return_value_policy::reference)
433 .def(
434 "get_service_hostmem",
435 [](AcceleratorConnection &acc) {
436 return acc.getService<services::HostMem>({});
437 },
438 py::return_value_policy::reference)
439 .def("get_accelerator", &AcceleratorConnection::getAccelerator,
440 py::return_value_policy::reference);
441
442 py::class_<Manifest>(m, "Manifest")
443 .def(py::init<Context &, std::string>())
444 .def_property_readonly("api_version", &Manifest::getApiVersion)
445 .def(
446 "build_accelerator",
447 [&](Manifest &m, AcceleratorConnection &conn) {
448 auto acc = m.buildAccelerator(conn);
449 conn.getServiceThread()->addPoll(*acc);
450 return acc;
451 },
452 py::return_value_policy::reference)
453 .def_property_readonly("type_table",
454 [](Manifest &m) {
455 std::vector<py::object> ret;
456 std::ranges::transform(m.getTypeTable(),
457 std::back_inserter(ret),
458 getPyType);
459 return ret;
460 })
461 .def_property_readonly("module_infos", &Manifest::getModuleInfos);
462}
This class provides a thread-safe interface to access the analysis results.
Abstract class representing a connection to an accelerator.
Definition Accelerator.h:79
ServiceClass * getService(AppIDPath id={}, std::string implName={}, ServiceImplDetails details={}, HWClientDetails clients={})
Get a typed reference to a particular service type.
Accelerator & getAccelerator()
AcceleratorServiceThread * getServiceThread()
Return a pointer to the accelerator 'service' thread (or threads).
std::string toStr() const
Definition Manifest.cpp:740
uint64_t getWidth() const
Definition Types.h:103
Unidirectional channels are the basic communication primitive between the host and accelerator.
Definition Ports.h:36
const Type * getType() const
Definition Ports.h:62
virtual void disconnect()=0
virtual void connect(std::optional< unsigned > bufferSize=std::nullopt)=0
Set up a connection to the accelerator.
const std::map< AppID, BundlePort & > & getPorts() const
Access the module's ports by ID.
Definition Design.h:76
const std::map< AppID, Instance * > & getChildren() const
Access the module's children by ID.
Definition Design.h:67
const std::vector< services::Service * > & getServices() const
Access the services provided by this module.
Definition Design.h:78
std::optional< ModuleInfo > getInfo() const
Access the module's metadata, if any.
Definition Design.h:58
const AppID getID() const
Get the instance's ID, which it will always have.
Definition Design.h:119
Class to parse a manifest.
Definition Manifest.h:39
A logical chunk of data representing serialized data.
Definition Common.h:104
const uint8_t * getBytes() const
Definition Common.h:113
size_t getSize() const
Get the size of the data in bytes.
Definition Common.h:122
A ChannelPort which reads data from the accelerator.
Definition Ports.h:124
virtual std::future< MessageData > readAsync()
Asynchronous read.
Definition Ports.cpp:77
Root class of the ESI type system.
Definition Types.h:27
ID getID() const
Definition Types.h:33
A ChannelPort which sends data to the accelerator.
Definition Ports.h:77
virtual void write(const MessageData &)=0
A very basic blocking write API.
virtual bool tryWrite(const MessageData &data)=0
A basic non-blocking write API.
A function call which gets attached to a service port.
Definition Services.h:306
A function call which gets attached to a service port.
Definition Services.h:263
virtual std::unique_ptr< HostMemRegion > allocate(std::size_t size, Options opts) const =0
Allocate a region of host memory in accelerator accessible address space.
virtual void unmapMemory(void *ptr) const
Unmap memory which was previously mapped with 'mapMemory'.
Definition Services.h:249
virtual bool mapMemory(void *ptr, std::size_t size, Options opts) const
Try to make a region of host memory accessible to the accelerator.
Definition Services.h:244
virtual uint64_t read(uint32_t addr) const
Read a 64-bit value from this region, not the global address space.
Definition Services.cpp:122
virtual void write(uint32_t addr, uint64_t data)
Write a 64-bit value to this region, not the global address space.
Definition Services.cpp:127
virtual RegionDescriptor getDescriptor() const
Get the offset (and size) of the region in the parent (usually global) MMIO address space.
Definition Services.h:167
virtual uint64_t read(uint32_t addr) const =0
Read a 64-bit value from the global MMIO space.
virtual void write(uint32_t addr, uint64_t data)=0
Write a 64-bit value to the global MMIO space.
const std::map< AppIDPath, RegionDescriptor > & getRegions() const
Get the regions of MMIO space that this service manages.
Definition Services.h:137
Parent class of all APIs modeled as 'services'.
Definition Services.h:46
Information about the Accelerator system.
Definition Services.h:100
virtual std::string getJsonManifest() const
Return the JSON-formatted system manifest.
Definition Services.cpp:40
virtual uint32_t getEsiVersion() const =0
Get the ESI version number to check version compatibility.
std::future< MessageData > read()
Definition Services.cpp:322
void connect()
Connect to a particular telemetry port.
Definition Services.cpp:308
Service for retrieving telemetry data from the accelerator.
Definition Services.h:344
PYBIND11_MODULE(esiCppAccel, m)
py::object getPyType(std::optional< const Type * > t)
Resolve a Type to the Python wrapper object.
std::unique_ptr< AcceleratorConnection > connect(Context &ctxt, const std::string &backend, const std::string &connection)
size_t hash_combine(size_t h1, size_t h2)
C++'s stdlib doesn't have a hash_combine function. This is a simple one.
Definition Utils.h:32
Definition esi.py:1
std::any value
Definition Common.h:59
std::optional< const Type * > type
Definition Common.h:60
RAII memory region for host memory.
Definition Services.h:209
virtual void * getPtr() const =0
Get a pointer to the host memory.
virtual std::size_t getSize() const =0
Options for allocating host memory.
Definition Services.h:227
Describe a region (slice) of MMIO space.
Definition Services.h:122
static handle cast(std::any src, return_value_policy, handle)
PYBIND11_TYPE_CASTER(std::any, const_name("object"))
static const void * get(const ChannelPort *port, const std::type_info *&type)
static const void * get(const Service *svc, const std::type_info *&type)