dma.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 __future__ import annotations
 
from pycde.common import Clock, Input, InputChannel, OutputChannel, Reset
from pycde.constructs import ControlReg, Mux, NamedWire, Wire
from pycde.module import modparams, generator
from pycde.types import Bits, Channel, StructType, Type, UInt
from pycde.support import clog2
from pycde import esi
 
 
@modparams
def OneItemBuffersToHost(client_type: Type):
  """Create a simple, non-performant DMA-based channel communication. Protocol:
 
  1) Host sends address of buffer address via MMIO write.
  2) Device writes data on channel with a byte '1' to said buffer address.
  3) Host polls the last byte in buffer for '1'.
  4) Data is copied out of buffer, last byte is set to '0', goto 1.
 
  Future improvement: support more than one buffer at once."""
 
  class OneItemBuffersToHost(esi.EngineModule):
 
    @property
    def TypeName(self):
      return "OneItemBuffersToHost"
 
    clk = Clock()
    rst = Reset()
    # The channel whose messages we are sending to the host.
    input_channel = InputChannel(client_type)
 
    # Since we cannot produce service requests (shortcoming of the ESI
    # compiler), the module (usually a service implementation) must issue the
    # service requests for us then connect the input ports.
    mmio = Input(esi.MMIO.read_write.type)
    # Compute the byte-aligned width of client_data. The DMA protocol
    # requires the valid flag to be the last byte of the transfer, which
    # only works when client_data is byte-aligned.
    client_data_bitwidth = client_type.bitwidth
    client_data_padded_bits = ((client_data_bitwidth + 7) // 8) * 8
    client_data_needs_pad = (client_data_padded_bits != client_data_bitwidth)
    # When padding is needed, widen client_data to Bits so the struct is
    # byte-aligned.  Otherwise keep the original type.
    client_data_wire_type = Bits(
        client_data_padded_bits) if client_data_needs_pad else client_type
    xfer_data_type = StructType([("valid", Bits(8)),
                                 ("client_data", client_data_wire_type)])
    hostmem_write = Input(esi.HostMem.write_req_bundle_type(xfer_data_type))
 
    @generator
    def build(ports):
      clk = ports.clk
      rst = ports.rst
 
      # Set up the MMIO interface to receive the buffer locations.
      mmio_resp_chan = Wire(Channel(Bits(64)))
      mmio_rw = ports.mmio
      mmio_cmd_chan_raw = mmio_rw.unpack(data=mmio_resp_chan)['cmd']
      mmio_cmd_chan, mmio_cmd_fork_resp = mmio_cmd_chan_raw.fork(clk, rst)
 
      # Create a response channel which always responds with 0.
      mmio_resp_data = NamedWire(Bits(64)(0), "mmio_resp_data")
      mmio_resp_chan.assign(
          mmio_cmd_fork_resp.transform(lambda _: mmio_resp_data))
 
      # Create a mailbox for each register. Overkill for one register, but may
      # be useful later on.
      _, _, mmio_cmd = mmio_cmd_chan.snoop()
      num_sinks = 2
      mmio_offset_words = NamedWire((mmio_cmd.offset.as_bits()[3:]).as_uint(),
                                    "mmio_offset_words")
      addr_above = mmio_offset_words >= UInt(32)(num_sinks)
      addr_is_zero = mmio_offset_words == UInt(32)(0)
      force_to_null = NamedWire(addr_above | ~addr_is_zero | mmio_cmd.write,
                                "force_to_null")
      cmd_sink_sel = Mux(force_to_null,
                         Bits(clog2(num_sinks))(0),
                         mmio_offset_words.as_bits()[:clog2(num_sinks)])
      mmio_data_only_chan = mmio_cmd_chan.transform(lambda m: m.data)
      mailbox_names = ["null", "buffer_loc"]
      demuxed = esi.ChannelDemux(mmio_data_only_chan, cmd_sink_sel, num_sinks)
      mailbox_mod = esi.Mailbox(Bits(64))
      mailboxes = [
          mailbox_mod(clk=clk,
                      rst=rst,
                      input=c,
                      instance_name="mailbox_" + name)
          for name, c in zip(mailbox_names, demuxed)
      ]
      [_, buffer_loc] = mailboxes
 
      # Join the buffer location channel with the input channel and send a write
      # message to hostmem.
      next_buffer_loc_chan = buffer_loc.output
      hostwr_type = esi.HostMem.write_req_channel_type(
          OneItemBuffersToHost.xfer_data_type)
      hostwr_joined = Channel.join(next_buffer_loc_chan, ports.input_channel)
 
      def _pad_client_data(raw):
        """Widen the client data to byte-aligned Bits for the DMA struct."""
        if not OneItemBuffersToHost.client_data_needs_pad:
          return raw
        # bitcast to Bits of original width, then zero-extend.
        return raw.bitcast(Bits(
            OneItemBuffersToHost.client_data_bitwidth)).pad_or_truncate(
                OneItemBuffersToHost.client_data_padded_bits)
 
      hostwr = hostwr_joined.transform(lambda joined: hostwr_type({
          "address": joined.a.as_uint(),
          "tag": 0,
          "data": {
              "valid": 1,
              "client_data": _pad_client_data(joined.b)
          },
      }))
      ports.hostmem_write.unpack(req=hostwr)
 
  return OneItemBuffersToHost
 
 
def OneItemBuffersFromHost(client_type: Type):
  """Create a simple, non-performant DMA-base from host communication channel.
 
  1) Host sends address of buffer address via MMIO write to register 0x08.
  2) Host sends address of completion address via MMIO write to register 0x10.
  3) Device reads data from said buffer and sends down the channel. Only keeps
      one transfer outstanding by buffering the read response locally before
      forwarding it.
  4) Device writes '1' to the first byte of the completion buffer to signal that
     the transfer is done.
  """
 
  class OneItemBuffersFromHost(esi.EngineModule):
 
    @property
    def TypeName(self):
      return "OneItemBuffersFromHost"
 
    clk = Clock()
    rst = Reset()
 
    # The channel whose messages we are sending to the host.
    output_channel = OutputChannel(client_type)
 
    # Since we cannot produce service requests (shortcoming of the ESI
    # compiler), the module (usually a service implementation) must issue the
    # service requests for us then connect the input ports.
    mmio = Input(esi.MMIO.read_write.type)
    xfer_data_type = Bits(8)
    hostmem_write = Input(esi.HostMem.write_req_bundle_type(xfer_data_type))
    hostmem_read = Input(esi.HostMem.read_bundle_type(client_type))
 
    @generator
    def build(ports):
      clk = ports.clk
      rst = ports.rst
 
      # Set up the MMIO interface to receive the buffer locations.
      mmio_resp_chan = Wire(Channel(Bits(64)))
      mmio_rw = ports.mmio
      mmio_cmd_chan_raw = mmio_rw.unpack(data=mmio_resp_chan)['cmd']
      mmio_cmd_chan, mmio_cmd_fork_resp = mmio_cmd_chan_raw.fork(clk, rst)
 
      # Create a response channel which always responds with 0.
      mmio_resp_data = NamedWire(Bits(64)(0), "mmio_resp_data")
      mmio_resp_chan.assign(
          mmio_cmd_fork_resp.transform(lambda _: mmio_resp_data))
 
      # Route the MMIO command
      _, _, mmio_cmd = mmio_cmd_chan.snoop()
      mailbox_names = ["null", "buffer_loc", "completion_addr"]
      num_sinks = len(mailbox_names)
      mmio_offset_words = NamedWire((mmio_cmd.offset.as_bits()[3:]).as_uint(),
                                    "mmio_offset_words")
      addr_above = mmio_offset_words >= UInt(32)(num_sinks)
      addr_is_zero = mmio_offset_words == UInt(32)(0)
      force_to_null = NamedWire(addr_above | ~addr_is_zero | mmio_cmd.write,
                                "force_to_null")
      cmd_sink_sel = Mux(force_to_null,
                         Bits(clog2(num_sinks))(0),
                         mmio_offset_words.as_bits()[:clog2(num_sinks)])
      mmio_data_only_chan = mmio_cmd_chan.transform(lambda m: m.data)
      demuxed = esi.ChannelDemux(mmio_data_only_chan, cmd_sink_sel, num_sinks)
      # Mailbox is intentionally always-ready and overwrite-on-write: if
      # software updates either address too early, the new value replaces the
      # stale one instead of backpressuring MMIO.
      mailbox_mod = esi.Mailbox(Bits(64))
      mailboxes = [
          mailbox_mod(clk=clk,
                      rst=rst,
                      input=c,
                      instance_name="mailbox_" + name)
          for name, c in zip(mailbox_names, demuxed)
      ]
      [_, buffer_loc, completion_loc] = mailboxes
      buffer_loc_for_read = buffer_loc.output
 
      output_chan = Wire(Channel(client_type))
      ports.output_channel = output_chan
      output_buf_ready = Wire(Bits(1), name="output_buf_ready")
 
      # Only keep one outstanding transfer. Once we can buffer a response
      # locally, issue the host read even if the downstream consumer has not
      # raised ready yet.
      read_req_accept = Wire(Bits(1), name="read_req_accept")
      buffer_loc_data, buffer_loc_valid = buffer_loc_for_read.unwrap(
          read_req_accept)
      read_req_valid = NamedWire(buffer_loc_valid & output_buf_ready,
                                 "read_req_valid")
      read_req, read_req_ready = Channel(esi.HostMem.ReadReqType).wrap(
          esi.HostMem.ReadReqType({
              "address": buffer_loc_data.as_uint(),
              "tag": 0,
          }), read_req_valid)
      read_req_xact = NamedWire(read_req_valid & read_req_ready,
                                "read_req_xact")
      read_req_accept.assign(read_req_xact)
 
      # Buffer the read response locally so forwarding the data and issuing the
      # completion write do not both need the shared HostMem write path in the
      # same cycle.
      read_resp = ports.hostmem_read.unpack(req=read_req)['resp']
      output_ready = Wire(Bits(1), name="output_ready")
      output_valid_reset = Wire(Bits(1), name="output_valid_reset")
      read_resp_ready = Wire(Bits(1), name="read_resp_ready")
      read_resp_msg, read_resp_valid = read_resp.unwrap(read_resp_ready)
      read_resp_xact = NamedWire(read_resp_valid & read_resp_ready,
                                 "read_resp_xact")
      output_valid = ControlReg(
          clk=clk,
          rst=rst,
          asserts=[read_resp_xact],
          resets=[output_valid_reset],
          name="output_valid",
      )
      output_data = read_resp_msg.data.reg(clk=clk,
                                           rst=rst,
                                           ce=read_resp_xact,
                                           name="output_data")
      output_buf_ready.assign((~output_valid | output_ready).as_bits())
      read_resp_ready.assign(output_buf_ready)
      output_valid_reset.assign(output_valid & output_ready)
      output_buf_chan, output_chan_ready = Channel(client_type).wrap(
          output_data, output_valid)
      output_chan.assign(output_buf_chan)
      output_ready.assign(output_chan_ready)
 
      # Once the data has been read into the local buffer, issue the completion
      # write independently of when the downstream consumer accepts that data.
      completion_pending_reset = Wire(Bits(1), name="completion_pending_reset")
      completion_pending = ControlReg(
          clk=clk,
          rst=rst,
          asserts=[read_resp_xact],
          resets=[completion_pending_reset],
          name="completion_pending",
      )
 
      write_ch_type = esi.HostMem.write_req_channel_type(
          OneItemBuffersFromHost.xfer_data_type)
      completion_loc_ready = Wire(Bits(1), name="completion_loc_ready")
      completion_loc_data, completion_loc_valid = completion_loc.output.unwrap(
          completion_loc_ready)
      completion_write_valid = NamedWire(
          completion_loc_valid & completion_pending, "completion_write_valid")
      write_done_chan, completion_write_ready = Channel(write_ch_type).wrap(
          write_ch_type({
              "address": completion_loc_data.as_uint(),
              "tag": 0,
              "data": Bits(8)(1)
          }), completion_write_valid)
      completion_write_xact = NamedWire(
          completion_write_valid & completion_write_ready,
          "completion_write_xact")
      completion_loc_ready.assign(completion_write_xact)
      completion_pending_reset.assign(completion_write_xact)
 
      # Unpack the write port, but ignore the write confirmation.
      ports.hostmem_write.unpack(req=write_done_chan)
 
  return OneItemBuffersFromHost