esiaccel 0.2.2__cp312-cp312-win_amd64.whl

esiaccel/__init__.py

@@ -0,0 +1,31 @@
+#  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
+import sys
+import os
+from .accelerator import AcceleratorConnection, Context, LogLevel
+
+from .esiCppAccel import (AppID, Type, BundleType, ChannelType, ArrayType,
+                          StructType, BitsType, UIntType, SIntType)
+
+__all__ = [
+    "AcceleratorConnection", "AppID", "Context", "LogLevel", "Type",
+    "BundleType", "ChannelType", "ArrayType", "StructType", "BitsType",
+    "UIntType", "SIntType"
+]
+
+if sys.platform == "win32":
+  """Ensure that ESI libraries are in the dll path on Windows. Necessary to
+  call when users build against the esiaccel-provided prebuilt CMake/prebuilt
+  libraries, before they are loaded via. python.
+  """
+  from .utils import get_dll_dir
+  os.add_dll_directory(str(get_dll_dir()))
+
+
+def connect(platform: str, connection_str: str) -> "AcceleratorConnection":
+  """Connect to an accelerator using the specified platform and connection
+  string."""
+  ctxt = Context.default()
+  return AcceleratorConnection(ctxt,
+                               ctxt.cpp_ctxt.connect(platform, connection_str))

esiaccel/accelerator.py

@@ -0,0 +1,134 @@
+# ===-----------------------------------------------------------------------===#
+#  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
+# ===-----------------------------------------------------------------------===#
+#
+# The structure of the Python classes and hierarchy roughly mirrors the C++
+# side, but wraps the C++ objects. The wrapper classes sometimes add convenience
+# functionality and serve to return wrapped versions of the returned objects.
+#
+# ===-----------------------------------------------------------------------===#
+
+from typing import Dict, List, Optional
+
+from .types import BundlePort
+from . import esiCppAccel as cpp
+
+LogLevel = cpp.LogLevel
+
+
+class Context:
+  """A context for ESI accelerator connections. The underlying C++ context owns
+  everything assocated with it including types, accelerator connections, and
+  the accelerator facade/interface (aka Accelerator) itself. It must not be
+  garbage collected while any accelerators or connections that it owns are still
+  in use as they will be disconnected and destroyed when the context is
+  destroyed."""
+
+  _default: Optional["Context"] = None
+
+  def __init__(self, log_level: cpp.LogLevel = cpp.LogLevel.Warning):
+    self.cpp_ctxt = cpp.Context()
+    self.set_stdio_logger(log_level)
+
+  @staticmethod
+  def default() -> "Context":
+    if Context._default is None:
+      Context._default = Context()
+    return Context._default
+
+  def set_stdio_logger(self, level: cpp.LogLevel):
+    self.cpp_ctxt.set_stdio_logger(level)
+
+  def connect(self, platform: str,
+              connection_str: str) -> "AcceleratorConnection":
+    return AcceleratorConnection(
+        self, self.cpp_ctxt.connect(platform, connection_str))
+
+
+class AcceleratorConnection:
+  """A connection to an ESI accelerator."""
+
+  def __init__(self, ctxt: Context, cpp_accel: cpp.AcceleratorConnection):
+    if not isinstance(ctxt, Context):
+      raise TypeError("ctxt must be a Context")
+    self.ctxt = ctxt
+    self.cpp_accel = cpp_accel
+
+  def manifest(self) -> cpp.Manifest:
+    """Get and parse the accelerator manifest."""
+    return cpp.Manifest(self.ctxt.cpp_ctxt,
+                        self.cpp_accel.sysinfo().json_manifest())
+
+  def sysinfo(self) -> cpp.SysInfo:
+    return self.cpp_accel.sysinfo()
+
+  def build_accelerator(self) -> "Accelerator":
+    return Accelerator(self.manifest().build_accelerator(self.cpp_accel))
+
+  def get_service_mmio(self) -> cpp.MMIO:
+    return self.cpp_accel.get_service_mmio()
+
+  def get_service_hostmem(self) -> cpp.HostMem:
+    return self.cpp_accel.get_service_hostmem()
+
+  def get_accelerator(self) -> "Accelerator":
+    """
+    Return an accelerator that may be owned by this accelerator connection.
+    If no accelerator is owned, will throw.
+    """
+    return Accelerator(self.cpp_accel.get_accelerator())
+
+
+from .esiCppAccel import HostMemOptions
+
+
+class HWModule:
+  """Represents either the top level or an instance of a hardware module."""
+
+  def __init__(self, parent: Optional["HWModule"], cpp_hwmodule: cpp.HWModule):
+    self.parent = parent
+    self.cpp_hwmodule = cpp_hwmodule
+
+  @property
+  def children(self) -> Dict[cpp.AppID, "Instance"]:
+    return {
+        name: Instance(self, inst)
+        for name, inst in self.cpp_hwmodule.children.items()
+    }
+
+  @property
+  def ports(self) -> Dict[cpp.AppID, BundlePort]:
+    return {
+        name: BundlePort(self, port)
+        for name, port in self.cpp_hwmodule.ports.items()
+    }
+
+  @property
+  def services(self) -> List[cpp.AppID]:
+    return self.cpp_hwmodule.services
+
+
+MMIO = cpp.MMIO
+
+
+class Instance(HWModule):
+  """Subclass of `HWModule` which represents a submodule instance. Adds an
+  AppID, which the top level doesn't have or need."""
+
+  def __init__(self, parent: Optional["HWModule"], cpp_instance: cpp.Instance):
+    super().__init__(parent, cpp_instance)
+    self.cpp_hwmodule: cpp.Instance = cpp_instance
+
+  @property
+  def id(self) -> cpp.AppID:
+    return self.cpp_hwmodule.id
+
+
+class Accelerator(HWModule):
+  """Root of the accelerator design hierarchy."""
+
+  def __init__(self, cpp_accelerator: cpp.Accelerator):
+    super().__init__(None, cpp_accelerator)
+    self.cpp_hwmodule = cpp_accelerator

esiaccel/cmake/esiaccelConfig.cmake

@@ -0,0 +1,49 @@
+add_library(esiaccel::ESICppRuntime SHARED IMPORTED)
+set_target_properties(esiaccel::ESICppRuntime PROPERTIES
+  INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_LIST_DIR}/../include"
+)
+
+if(WIN32)
+  set_target_properties(esiaccel::ESICppRuntime PROPERTIES
+    IMPORTED_LOCATION "${CMAKE_CURRENT_LIST_DIR}/../ESICppRuntime.dll"
+    IMPORTED_IMPLIB "${CMAKE_CURRENT_LIST_DIR}/../ESICppRuntime.lib"
+  )
+else()
+  set_target_properties(esiaccel::ESICppRuntime PROPERTIES
+    IMPORTED_LOCATION "${CMAKE_CURRENT_LIST_DIR}/.././libESICppRuntime.so"
+  )
+endif()
+
+add_library(esiaccel::CosimRpc SHARED IMPORTED)
+set_target_properties(esiaccel::CosimRpc PROPERTIES
+  INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_LIST_DIR}/../include"
+  INTERFACE_LINK_LIBRARIES esiaccel::ESICppRuntime
+)
+
+if(WIN32)
+  set_target_properties(esiaccel::CosimRpc PROPERTIES
+    IMPORTED_LOCATION "${CMAKE_CURRENT_LIST_DIR}/../CosimRpc.dll"
+    IMPORTED_IMPLIB "${CMAKE_CURRENT_LIST_DIR}/../CosimRpc.lib"
+  )
+else()
+  set_target_properties(esiaccel::CosimRpc PROPERTIES
+    IMPORTED_LOCATION "${CMAKE_CURRENT_LIST_DIR}/.././libCosimRpc.so"
+  )
+endif()
+
+add_library(esiaccel::CosimBackend SHARED IMPORTED)
+set_target_properties(esiaccel::CosimBackend PROPERTIES
+  INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_LIST_DIR}/../include"
+  INTERFACE_LINK_LIBRARIES "esiaccel::ESICppRuntime;esiaccel::CosimRpc"
+)
+
+if(WIN32)
+  set_target_properties(esiaccel::CosimBackend PROPERTIES
+    IMPORTED_LOCATION "${CMAKE_CURRENT_LIST_DIR}/../CosimBackend.dll"
+    IMPORTED_IMPLIB "${CMAKE_CURRENT_LIST_DIR}/../CosimBackend.lib"
+  )
+else()
+  set_target_properties(esiaccel::CosimBackend PROPERTIES
+    IMPORTED_LOCATION "${CMAKE_CURRENT_LIST_DIR}/.././libCosimBackend.so"
+  )
+endif()

esiaccel/codegen.py

@@ -0,0 +1,197 @@
+#  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
+
+# Code generation from ESI manifests to source code. C++ header support included
+# with the runtime, though it is intended to be extensible for other languages.
+
+from typing import List, TextIO, Type, Optional
+from .accelerator import AcceleratorConnection, Context
+from .esiCppAccel import ModuleInfo
+from . import types
+
+import argparse
+from pathlib import Path
+import textwrap
+import sys
+
+_thisdir = Path(__file__).absolute().resolve().parent
+
+
+class Generator:
+  """Base class for all generators."""
+
+  language: Optional[str] = None
+
+  def __init__(self, conn: AcceleratorConnection):
+    self.manifest = conn.manifest()
+
+  def generate(self, output_dir: Path, system_name: str):
+    raise NotImplementedError("Generator.generate() must be overridden")
+
+
+class CppGenerator(Generator):
+  """Generate C++ headers from an ESI manifest."""
+
+  language = "C++"
+
+  # Supported bit widths for lone integer types.
+  int_width_support = set([8, 16, 32, 64])
+
+  def get_type_str(self, type: types.ESIType) -> str:
+    """Get the textual code for the storage class of a type.
+
+    Examples: uint32_t, int64_t, CustomStruct."""
+
+    if isinstance(type, (types.BitsType, types.IntType)):
+      if type.bit_width not in self.int_width_support:
+        raise ValueError(f"Unsupported integer width: {type.bit_width}")
+      if isinstance(type, (types.BitsType, types.UIntType)):
+        return f"uint{type.bit_width}_t"
+      return f"int{type.bit_width}_t"
+    raise NotImplementedError(f"Type '{type}' not supported for C++ generation")
+
+  def get_consts_str(self, module_info: ModuleInfo) -> str:
+    """Get the C++ code for a constant in a module."""
+    const_strs: List[str] = [
+        f"static constexpr {self.get_type_str(const.type)} "
+        f"{name} = 0x{const.value:x};"
+        for name, const in module_info.constants.items()
+    ]
+    return "\n".join(const_strs)
+
+  def write_modules(self, output_dir: Path, system_name: str):
+    """Write the C++ header. One for each module in the manifest."""
+
+    for module_info in self.manifest.module_infos:
+      s = f"""
+      /// Generated header for {system_name} module {module_info.name}.
+      #pragma once
+      #include "types.h"
+
+      namespace {system_name} {{
+      class {module_info.name} {{
+      public:
+        {self.get_consts_str(module_info)}
+      }};
+      }} // namespace {system_name}
+      """
+
+      hdr_file = output_dir / f"{module_info.name}.h"
+      with open(hdr_file, "w") as hdr:
+        hdr.write(textwrap.dedent(s))
+
+  def write_type(self, hdr: TextIO, type: types.ESIType):
+    if isinstance(type, (types.BitsType, types.IntType)):
+      # Bit vector types use standard C++ types.
+      return
+    raise NotImplementedError(f"Type '{type}' not supported for C++ generation")
+
+  def write_types(self, output_dir: Path, system_name: str):
+    hdr_file = output_dir / "types.h"
+    with open(hdr_file, "w") as hdr:
+      hdr.write(
+          textwrap.dedent(f"""
+      // Generated header for {system_name} types.
+      #pragma once
+
+      #include <cstdint>
+
+      namespace {system_name} {{
+      """))
+
+      for type in self.manifest.type_table:
+        try:
+          self.write_type(hdr, type)
+        except NotImplementedError:
+          sys.stderr.write(
+              f"Warning: type '{type}' not supported for C++ generation\n")
+
+      hdr.write(
+          textwrap.dedent(f"""
+      }} // namespace {system_name}
+      """))
+
+  def generate(self, output_dir: Path, system_name: str):
+    self.write_types(output_dir, system_name)
+    self.write_modules(output_dir, system_name)
+
+
+def run(generator: Type[Generator] = CppGenerator,
+        cmdline_args=sys.argv) -> int:
+  """Create and run a generator reading options from the command line."""
+
+  argparser = argparse.ArgumentParser(
+      description=f"Generate {generator.language} headers from an ESI manifest",
+      formatter_class=argparse.RawDescriptionHelpFormatter,
+      epilog=textwrap.dedent("""
+        Can read the manifest from either a file OR a running accelerator.
+
+        Usage examples:
+          # To read the manifest from a file:
+          esi-cppgen --file /path/to/manifest.json
+
+          # To read the manifest from a running accelerator:
+          esi-cppgen --platform cosim --connection localhost:1234
+      """))
+
+  argparser.add_argument("--file",
+                         type=str,
+                         default=None,
+                         help="Path to the manifest file.")
+  argparser.add_argument(
+      "--platform",
+      type=str,
+      help="Name of platform for live accelerator connection.")
+  argparser.add_argument(
+      "--connection",
+      type=str,
+      help="Connection string for live accelerator connection.")
+  argparser.add_argument(
+      "--output-dir",
+      type=str,
+      default="esi",
+      help="Output directory for generated files. Recommend adding either `esi`"
+      " or the system name to the end of the path so as to avoid header name"
+      "conflicts. Defaults to `esi`")
+  argparser.add_argument(
+      "--system-name",
+      type=str,
+      default="esi_system",
+      help="Name of the ESI system. For C++, this will be the namespace.")
+
+  if (len(cmdline_args) <= 1):
+    argparser.print_help()
+    return 1
+  args = argparser.parse_args(cmdline_args[1:])
+
+  if args.file is not None and args.platform is not None:
+    print("Cannot specify both --file and --platform")
+    return 1
+
+  conn: AcceleratorConnection
+  if args.file is not None:
+    conn = Context.default().connect("trace", f"-:{args.file}")
+  elif args.platform is not None:
+    if args.connection is None:
+      print("Must specify --connection with --platform")
+      return 1
+    conn = Context.default().connect(args.platform, args.connection)
+  else:
+    print("Must specify either --file or --platform")
+    return 1
+
+  output_dir = Path(args.output_dir)
+  if output_dir.exists() and not output_dir.is_dir():
+    print(f"Output directory {output_dir} is not a directory")
+    return 1
+  if not output_dir.exists():
+    output_dir.mkdir(parents=True)
+
+  gen = generator(conn)
+  gen.generate(output_dir, args.system_name)
+  return 0
+
+
+if __name__ == '__main__':
+  sys.exit(run())

esiaccel/cosim/Cosim_DpiPkg.sv

@@ -0,0 +1,85 @@
+//===- Cosim_DpiPkg.sv - ESI cosim DPI declarations ---------*- verilog -*-===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+//
+// Package: Cosim_DpiPkg
+//
+// DPI-exposed funcs for cosimserver cosimulation unit-test.
+//
+//===----------------------------------------------------------------------===//
+
+package Cosim_DpiPkg;
+
+// --------------------- Cosim RPC Server --------------------------------------
+
+// Start cosimserver (spawns server for HW-initiated work, listens for
+// connections from new SW-clients).
+import "DPI-C" sv2cCosimserverInit = function int cosim_init();
+
+// Teardown cosimserver (disconnects from primary server port, stops connections
+// from active clients).
+import "DPI-C" sv2cCosimserverFinish = function void cosim_finish();
+
+// --------------------- Endpoint Management -----------------------------------
+
+// Register simulated device endpoints.
+// - return 0 on success, non-zero on failure (duplicate EP registered).
+import "DPI-C" sv2cCosimserverEpRegister =
+  function int cosim_ep_register(
+    // The endpoint ID.
+    input string endpoint_id,
+    // The ESI type id which the _RPC client_ is sending us.
+    input string from_host_type_id,
+    // The send types max size, in bytes.
+    input int from_host_type_size,
+    // The ESI type id which we are sending to the _RPC client_.
+    input string to_host_type_id,
+    // The recv types max size, in bytes.
+    input int to_host_type_size);
+
+// --------------------- Endpoint Accessors ------------------------------------
+
+// Attempt to send data to a client.
+// - return 0 on success, negative on failure (unregistered EP).
+import "DPI-C" sv2cCosimserverEpTryPut =
+  function int cosim_ep_tryput(
+    // The ID of the endpoint to which the data should be sent.
+    input string endpoint_id,
+    // A data buffer.
+    input byte unsigned data[],
+    // (Optional) Size of the buffer. If negative, will be dynamically detected.
+    input int data_size = -1
+    );
+
+// Attempt to recieve data from a client.
+//   - Returns negative when call failed (e.g. EP not registered).
+//   - If no message, return 0 with size_bytes == 0.
+//   - Assumes buffer is large enough to contain entire message. Fails if not
+//   large enough. (In the future, will add support for getting the message into
+//   a fixed-size buffer over multiple calls.)
+import "DPI-C" sv2cCosimserverEpTryGet =
+  function int cosim_ep_tryget(
+    // The ID of the endpoint from which data should be recieved.
+    input string endpoint_id,
+    // The buffer in which to put the data. This should be 'output', but the
+    // open source simulator Verilator doesn't seem to have a way to do this.
+    inout byte unsigned data[],
+    // Input: indicates the size of the data[] buffer. If -1, dynamically detect
+    // size.
+    // Output: the size of the message.
+    inout int unsigned data_size
+    );
+
+// --------------------- Manifest ----------------------------------------------
+
+import "DPI-C" sv2cCosimserverSetManifest =
+  function void cosim_set_manifest(
+    input int signed esi_version,
+    input byte unsigned compressed_manifest[]
+  );
+
+endpackage // Cosim_DpiPkg