cosim.py

Go to the documentation of this file.

#  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
 
from typing import Callable, Optional, Tuple, Type
 
from pycde.common import AppID, Clock, Input, Output
from pycde.module import Module, generator
from pycde.support import get_user_loc
from pycde.system import System
from pycde.signals import ChannelSignal
from pycde.types import (Bits, Channel, StructType, UInt)
from pycde.constructs import Wire
from pycde import esi
 
from .common import (ChannelEngineService, ChannelHostMem, ChannelMMIO,
                     DEFAULT_MAX_READ_REQUEST_BYTES,
                     DEFAULT_MAX_WRITE_PAYLOAD_BYTES, DesignResetController,
                     ResetCycles, TelemetryMMIO)
from .dma import OneItemBuffersFromHost, OneItemBuffersToHost
 
from pycde.circt import ir
from pycde.circt.dialects import esi as raw_esi
 
from pathlib import Path
 
__root_dir__ = Path(__file__).parent.parent
 
 
def CosimBSP(
    user_module: Type[Module],
    dma_engine_pair: Optional[Tuple[Callable, Callable]] = None,
    channel_service: Optional[Type[esi.ServiceImplementation]] = None,
    max_outstanding_reads: int = 4,
    hostmem_width: int = 64,
) -> Module:
  """Wrap and return a cosimulation 'board support package' containing
  'user_module'.
 
  By default, channels use the native cosim transport. 'dma_engine_pair' is a
  (to_host_gen, from_host_gen) pair used by ChannelEngineService to create one
  DMA engine per channel.
 
  For custom implementations, including engines shared by multiple channels,
  'channel_service' accepts an esi.ServiceImplementation subclass, not an
  instance. It must have exactly the input ports 'clk = Clock()' and
  'rst = Reset()'. The BSP instantiates it with decl=None for the builtin
  ChannelService and appid=esi.AppID("__channel_engines"). Its generator may
  issue esi.MMIO and esi.HostMem requests, which the BSP will satisfy.
 
  Passing both 'dma_engine_pair' and 'channel_service' raises ValueError.
 
  'max_outstanding_reads' is the per-client limit on logical HostMem read
  requests in flight. The cosim host services each read request in order, so
  more than one is safe; the default of 4 keeps the multi-outstanding read path
  exercised in simulation.
 
  'hostmem_width' is the upstream HostMem read and write width in bits. It must
  be a power of two and at least 8. The host runtime discovers it automatically.
  Wider beats reduce transport messages for wide transfers, without combining
  separate narrow requests or changing completion semantics.
  """
  if (type(hostmem_width) is not int or hostmem_width < 8 or
      hostmem_width & (hostmem_width - 1)):
    raise ValueError("hostmem_width must be a power of two and at least 8")
  if dma_engine_pair is not None and channel_service is not None:
    raise ValueError(
        "dma_engine_pair and channel_service are mutually exclusive")
  if dma_engine_pair is not None:
    channel_service = ChannelEngineService(*dma_engine_pair)
 
  class ESI_Cosim_UserTopWrapper(Module):
    """Wrap the user module along with 'standard' service generators so that
    those generators can issue their own service requests to be picked up by the
    actual top-level catch-all cosim service generator."""
 
    clk = Clock()
    rst = Input(Bits(1))
 
    mmio = Input(esi.MMIO.read_write.type)
 
    HostMemWidth = hostmem_width
 
    ChannelHostMemModule = ChannelHostMem(
        read_width=HostMemWidth,
        write_width=HostMemWidth,
        max_read_request_bytes=max(DEFAULT_MAX_READ_REQUEST_BYTES,
                                   HostMemWidth // 8),
        max_write_payload_bytes=max(DEFAULT_MAX_WRITE_PAYLOAD_BYTES,
                                    HostMemWidth // 8),
        max_outstanding_reads=max_outstanding_reads,
        round_read_lengths=False)
 
    hostmem_read = ChannelHostMemModule.read
    hostmem_write = ChannelHostMemModule.write
 
    # Asserted for one cycle when the design requests a reset (via an MMIO write
    # to the header). Consumed by the top-level module which performs the reset.
    # NOTE: must be declared after 'hostmem_read'/'hostmem_write' so it does not
    # perturb their output port indices (they alias the sub-module's shared
    # Output objects, whose '.idx' is reused for the instance output lookup).
    reset_request = Output(Bits(1))
 
    @generator
    def build(ports):
      user_module(clk=ports.clk, rst=ports.rst)
      TelemetryMMIO(esi.Telemetry,
                    appid=esi.AppID("__telemetry"),
                    clk=ports.clk,
                    rst=ports.rst)
 
      if channel_service is not None:
        channel_service(None,
                        appid=esi.AppID("__channel_engines"),
                        clk=ports.clk,
                        rst=ports.rst)
 
      mmio = ChannelMMIO(esi.MMIO,
                         appid=esi.AppID("__cosim_mmio"),
                         clk=ports.clk,
                         rst=ports.rst,
                         cmd=ports.mmio)
      ports.reset_request = mmio.reset_request
 
      # Instantiate a hostmem service generator which multiplexes requests to a
      # either a single read or write channel. Get those channels and transform
      # them into callbacks.
      hostmem = ESI_Cosim_UserTopWrapper.ChannelHostMemModule(
          decl=esi.HostMem,
          appid=esi.AppID("__cosim_hostmem"),
          clk=ports.clk,
          rst=ports.rst)
      ports.hostmem_read = hostmem.read
      ports.hostmem_write = hostmem.write
 
  class ESI_Cosim_Top(Module):
    clk = Clock()
    rst = Input(Bits(1))
 
    @generator
    def build(ports):
      System.current().platform = "cosim"
 
      mmio_read_write = esi.FuncService.get(
          esi.AppID("__cosim_mmio_read_write"), esi.MMIO.read_write.type)
 
      # The design can request a reset via an MMIO write to the header. Once
      # requested, reset the entire design (but not the cosim link) after a
      # fixed number of cycles. The reset controller is driven by the external
      # reset only so its countdown is not disturbed by the reset it generates.
      design_reset = Wire(Bits(1))
      reset_pending = Wire(Bits(1))
      combined_rst = ports.rst | design_reset
 
      # Once a reset has been requested, stop accepting *new* MMIO transactions
      # so that none is in flight when the design (including the MMIO plane) is
      # actually reset 'ResetCycles' cycles later. Any already-accepted
      # transaction has that window to drain; a command held here is released
      # once the reset completes and the MMIO plane is back up. The gate is
      # purely combinational off the (registered) 'reset_pending', so it blocks
      # at a clean cycle boundary: when pending is high the command is not
      # presented downstream and the host sees back-pressure (so it retains the
      # command), and neither side completes a handshake. This logic lives in
      # the external-reset domain so it is not cleared by the reset it guards.
      mmio_resp = Wire(Channel(esi.MMIODataType))
      host_cmd = mmio_read_write.unpack(data=mmio_resp)['cmd']
      gate_ready = Wire(Bits(1))
      cmd_payload, cmd_valid = host_cmd.unwrap(gate_ready)
      fwd_valid = (cmd_valid & ~reset_pending).as_bits()
      gated_cmd, fwd_ready = host_cmd.type.wrap(cmd_payload, fwd_valid)
      gate_ready.assign((fwd_ready & ~reset_pending).as_bits())
      gated_mmio, gated_froms = esi.MMIO.read_write.type.pack(cmd=gated_cmd)
      mmio_resp.assign(gated_froms['data'])
 
      wrapper = ESI_Cosim_UserTopWrapper(clk=ports.clk,
                                         rst=combined_rst,
                                         mmio=gated_mmio)
      reset_controller = DesignResetController(ResetCycles)(
          clk=ports.clk, rst=ports.rst, reset_request=wrapper.reset_request)
      design_reset.assign(reset_controller.design_reset)
      reset_pending.assign(reset_controller.reset_pending)
 
      # While a reset is pending, drop host-driven responses to the design's
      # hostmem service. In-flight requests issued before the reset will have
      # their responses arrive after the design (and its hostmem tag/demux
      # state) has been reset; delivering them would corrupt the fresh state or
      # hang on a response the reset design never consumes. Draining them here
      # (assert ready toward the host, never present a valid downstream) keeps
      # the host response channels flowing. This lives in the external-reset
      # domain so it is not cleared by the reset it guards.
      def drop_while_resetting(chan: ChannelSignal) -> ChannelSignal:
        src_ready = Wire(Bits(1))
        payload, valid = chan.unwrap(src_ready)
        fwd_valid = (valid & ~reset_pending).as_bits()
        gated, dn_ready = chan.type.wrap(payload, fwd_valid)
        src_ready.assign((dn_ready | reset_pending).as_bits())
        return gated
 
      resp_channel = esi.ChannelService.from_host(
          esi.AppID("__cosim_hostmem_read_resp"),
          StructType([
              ("tag", UInt(8)),
              ("data", Bits(ESI_Cosim_UserTopWrapper.HostMemWidth)),
              ("last", Bits(1)),
          ]))
      req = wrapper.hostmem_read.unpack(
          resp=drop_while_resetting(resp_channel))['req']
      esi.ChannelService.to_host(esi.AppID("__cosim_hostmem_read_req"), req)
 
      ack_wire = Wire(Channel(UInt(8)))
      write_req = wrapper.hostmem_write.unpack(ackTag=ack_wire)['req']
      ack_tag = esi.CallService.call(esi.AppID("__cosim_hostmem_write"),
                                     write_req, UInt(8))
      ack_wire.assign(drop_while_resetting(ack_tag))
 
      cosim_svc = raw_esi.ServiceInstanceOp(
          result=[],
          appID=AppID("cosim")._appid,
          service_symbol=None,
          impl_type=ir.StringAttr.get("cosim"),
          inputs=[ports.clk.value, ports.rst.value],
          loc=get_user_loc())
      core_freq = System.current().core_freq
      if core_freq is not None:
        cosim_svc.operation.attributes[
            "esi.core_clock_frequency_hz"] = ir.IntegerAttr.get(
                ir.IntegerType.get_unsigned(64), core_freq)
 
  return ESI_Cosim_Top
 
 
def CosimBSP_DMA(user_module: Type[Module],
                 max_outstanding_reads: int = 4,
                 hostmem_width: int = 64) -> Module:
  """CosimBSP with one-item DMA engines; accepts the same HostMem widths."""
  return CosimBSP(user_module,
                  channel_service=ChannelEngineService(OneItemBuffersToHost,
                                                       OneItemBuffersFromHost),
                  max_outstanding_reads=max_outstanding_reads,
                  hostmem_width=hostmem_width)