nmigen_soc/csr/bus.py

   1 import enum
   2 from nmigen import *
   3 from nmigen.utils import log2_int
   4
   5 from ..memory import MemoryMap
   6
   7
   8 __all__ = ["Element", "Interface", "Decoder", "Multiplexer"]
   9
  10
  11 class Element(Record):
  12     class Access(enum.Enum):
  13         """Register access mode.
  14
  15         Coarse access mode for the entire register. Individual fields can have more restrictive
  16         access mode, e.g. R/O fields can be a part of an R/W register.
  17         """
  18         R  = "r"
  19         W  = "w"
  20         RW = "rw"
  21
  22         def readable(self):
  23             return self == self.R or self == self.RW
  24
  25         def writable(self):
  26             return self == self.W or self == self.RW
  27
  28     """Peripheral-side CSR interface.
  29
  30     A low-level interface to a single atomically readable and writable register in a peripheral.
  31     This interface supports any register width and semantics, provided that both reads and writes
  32     always succeed and complete in one cycle.
  33
  34     Parameters
  35     ----------
  36     width : int
  37         Width of the register.
  38     access : :class:`Access`
  39         Register access mode.
  40     name : str
  41         Name of the underlying record.
  42
  43     Attributes
  44     ----------
  45     r_data : Signal(width)
  46         Read data. Must be always valid, and is sampled when ``r_stb`` is asserted.
  47     r_stb : Signal()
  48         Read strobe. Registers with read side effects should perform the read side effect when this
  49         strobe is asserted.
  50     w_data : Signal(width)
  51         Write data. Valid only when ``w_stb`` is asserted.
  52     w_stb : Signal()
  53         Write strobe. Registers should update their value or perform the write side effect when
  54         this strobe is asserted.
  55     """
  56     def __init__(self, width, access, *, name=None, src_loc_at=0):
  57         if not isinstance(width, int) or width < 0:
  58             raise ValueError("Width must be a non-negative integer, not {!r}"
  59                              .format(width))
  60         if not isinstance(access, Element.Access) and access not in ("r", "w", "rw"):
  61             raise ValueError("Access mode must be one of \"r\", \"w\", or \"rw\", not {!r}"
  62                              .format(access))
  63         self.width  = width
  64         self.access = Element.Access(access)
  65
  66         layout = []
  67         if self.access.readable():
  68             layout += [
  69                 ("r_data", width),
  70                 ("r_stb",  1),
  71             ]
  72         if self.access.writable():
  73             layout += [
  74                 ("w_data", width),
  75                 ("w_stb",  1),
  76             ]
  77         super().__init__(layout, name=name, src_loc_at=1)
  78
  79     # FIXME: get rid of this
  80     __hash__ = object.__hash__
  81
  82
  83 class Interface(Record):
  84     """CPU-side CSR interface.
  85
  86     A low-level interface to a set of atomically readable and writable peripheral CSR registers.
  87
  88     Operation
  89     ---------
  90
  91     CSR registers mapped to the CSR bus are split into chunks according to the bus data width.
  92     Each chunk is assigned a consecutive address on the bus. This allows accessing CSRs of any
  93     size using any datapath width.
  94
  95     When the first chunk of a register is read, the value of a register is captured, and reads
  96     from subsequent chunks of the same register return the captured values. When any chunk except
  97     the last chunk of a register is written, the written value is captured; a write to the last
  98     chunk writes the captured value to the register. This allows atomically accessing CSRs larger
  99     than datapath width.
 100
 101     Parameters
 102     ----------
 103     addr_width : int
 104         Address width. At most ``(2 ** addr_width) * data_width`` register bits will be available.
 105     data_width : int
 106         Data width. Registers are accessed in ``data_width`` sized chunks.
 107     alignment : int
 108         Register and window alignment. See :class:`MemoryMap`.
 109     name : str
 110         Name of the underlying record.
 111
 112     Attributes
 113     ----------
 114     memory_map : MemoryMap
 115         Map of the bus.
 116     addr : Signal(addr_width)
 117         Address for reads and writes.
 118     r_data : Signal(data_width)
 119         Read data. Valid on the next cycle after ``r_stb`` is asserted. Otherwise, zero. (Keeping
 120         read data of an unused interface at zero simplifies multiplexers.)
 121     r_stb : Signal()
 122         Read strobe. If ``addr`` points to the first chunk of a register, captures register value
 123         and causes read side effects to be performed (if any). If ``addr`` points to any chunk
 124         of a register, latches the captured value to ``r_data``. Otherwise, latches zero
 125         to ``r_data``.
 126     w_data : Signal(data_width)
 127         Write data. Must be valid when ``w_stb`` is asserted.
 128     w_stb : Signal()
 129         Write strobe. If ``addr`` points to the last chunk of a register, writes captured value
 130         to the register and causes write side effects to be performed (if any). If ``addr`` points
 131         to any chunk of a register, latches ``w_data`` to the captured value. Otherwise, does
 132         nothing.
 133     """
 134
 135     def __init__(self, *, addr_width, data_width, alignment=0, name=None):
 136         if not isinstance(addr_width, int) or addr_width <= 0:
 137             raise ValueError("Address width must be a positive integer, not {!r}"
 138                              .format(addr_width))
 139         if not isinstance(data_width, int) or data_width <= 0:
 140             raise ValueError("Data width must be a positive integer, not {!r}"
 141                              .format(data_width))
 142         self.addr_width = addr_width
 143         self.data_width = data_width
 144         self.memory_map = MemoryMap(addr_width=addr_width, data_width=data_width,
 145                                     alignment=alignment)
 146
 147         super().__init__([
 148             ("addr",    addr_width),
 149             ("r_data",  data_width),
 150             ("r_stb",   1),
 151             ("w_data",  data_width),
 152             ("w_stb",   1),
 153         ], name=name, src_loc_at=1)
 154
 155
 156 class Multiplexer(Elaboratable):
 157     """CSR register multiplexer.
 158
 159     An address-based multiplexer for CSR registers implementing atomic updates.
 160
 161     Latency
 162     -------
 163
 164     Writes are registered, and are performed 1 cycle after ``w_stb`` is asserted.
 165
 166     Alignment
 167     ---------
 168
 169     Because the CSR bus conserves logic and routing resources, it is common to e.g. access
 170     a CSR bus with an *n*-bit data path from a CPU with a *k*-bit datapath (*k>n*) in cases
 171     where CSR access latency is less important than resource usage. In this case, two strategies
 172     are possible for connecting the CSR bus to the CPU:
 173         * The CPU could access the CSR bus directly (with no intervening logic other than simple
 174           translation of control signals). In this case, the register alignment should be set
 175           to 1, and each *w*-bit register would occupy *ceil(w/n)* addresses from the CPU
 176           perspective, requiring the same amount of memory instructions to access.
 177         * The CPU could also access the CSR bus through a width down-converter, which would issue
 178           *k/n* CSR accesses for each CPU access. In this case, the register alignment should be
 179           set to *k/n*, and each *w*-bit register would occupy *ceil(w/k)* addresses from the CPU
 180           perspective, requiring the same amount of memory instructions to access.
 181
 182     If alignment is greater than 1, it affects which CSR bus write is considered a write to
 183     the last register chunk. For example, if a 24-bit register is used with a 8-bit CSR bus and
 184     a CPU with a 32-bit datapath, a write to this register requires 4 CSR bus writes to complete
 185     and the 4th write is the one that actually writes the value to the register. This allows
 186     determining write latency solely from the amount of addresses the register occupies in
 187     the CPU address space, and the width of the CSR bus.
 188
 189     Parameters
 190     ----------
 191     addr_width : int
 192         Address width. See :class:`Interface`.
 193     data_width : int
 194         Data width. See :class:`Interface`.
 195     alignment : int
 196         Register alignment. See :class:`Interface`.
 197
 198     Attributes
 199     ----------
 200     bus : :class:`Interface`
 201         CSR bus providing access to registers.
 202     """
 203     def __init__(self, *, addr_width, data_width, alignment=0):
 204         self.bus  = Interface(addr_width=addr_width, data_width=data_width, alignment=alignment,
 205                               name="csr")
 206         self._map = self.bus.memory_map
 207
 208     def align_to(self, alignment):
 209         """Align the implicit address of the next register.
 210
 211         See :meth:`MemoryMap.align_to` for details.
 212         """
 213         return self._map.align_to(alignment)
 214
 215     def add(self, element, *, addr=None, alignment=None):
 216         """Add a register.
 217
 218         See :meth:`MemoryMap.add_resource` for details.
 219         """
 220         if not isinstance(element, Element):
 221             raise TypeError("Element must be an instance of csr.Element, not {!r}"
 222                             .format(element))
 223
 224         size = (element.width + self.bus.data_width - 1) // self.bus.data_width
 225         return self._map.add_resource(element, size=size, addr=addr, alignment=alignment)
 226
 227     def elaborate(self, platform):
 228         m = Module()
 229
 230         # Instead of a straightforward multiplexer for reads, use a per-element address comparator,
 231         # AND the shadow register chunk with the comparator output, and OR all of those together.
 232         # If the toolchain doesn't already synthesize multiplexer trees this way, this trick can
 233         # save a significant amount of logic, since e.g. one 4-LUT can pack one 2-MUX, but two
 234         # 2-AND or 2-OR gates.
 235         r_data_fanin = 0
 236
 237         for elem, (elem_start, elem_end) in self._map.resources():
 238             shadow = Signal(elem.width, name="{}__shadow".format(elem.name))
 239             if elem.access.readable():
 240                 shadow_en = Signal(elem_end - elem_start, name="{}__shadow_en".format(elem.name))
 241                 m.d.sync += shadow_en.eq(0)
 242             if elem.access.writable():
 243                 m.d.comb += elem.w_data.eq(shadow)
 244                 m.d.sync += elem.w_stb.eq(0)
 245
 246             # Enumerate every address used by the register explicitly, rather than using
 247             # arithmetic comparisons, since some toolchains (e.g. Yosys) are too eager to infer
 248             # carry chains for comparisons, even with a constant. (Register sizes don't have
 249             # to be powers of 2.)
 250             with m.Switch(self.bus.addr):
 251                 for chunk_offset, chunk_addr in enumerate(range(elem_start, elem_end)):
 252                     shadow_slice = shadow.word_select(chunk_offset, self.bus.data_width)
 253
 254                     with m.Case(chunk_addr):
 255                         if elem.access.readable():
 256                             r_data_fanin |= Mux(shadow_en[chunk_offset], shadow_slice, 0)
 257                             if chunk_addr == elem_start:
 258                                 m.d.comb += elem.r_stb.eq(self.bus.r_stb)
 259                                 with m.If(self.bus.r_stb):
 260                                     m.d.sync += shadow.eq(elem.r_data)
 261                             # Delay by 1 cycle, allowing reads to be pipelined.
 262                             m.d.sync += shadow_en.eq(self.bus.r_stb << chunk_offset)
 263
 264                         if elem.access.writable():
 265                             if chunk_addr == elem_end - 1:
 266                                 # Delay by 1 cycle, avoiding combinatorial paths through
 267                                 # the CSR bus and into CSR registers.
 268                                 m.d.sync += elem.w_stb.eq(self.bus.w_stb)
 269                             with m.If(self.bus.w_stb):
 270                                 m.d.sync += shadow_slice.eq(self.bus.w_data)
 271
 272         m.d.comb += self.bus.r_data.eq(r_data_fanin)
 273
 274         return m
 275
 276
 277 class Decoder(Elaboratable):
 278     """CSR bus decoder.
 279
 280     An address decoder for subordinate CSR buses.
 281
 282     Usage
 283     -----
 284
 285     Although there is no functional difference between adding a set of registers directly to
 286     a :class:`Multiplexer` and adding a set of registers to multiple :class:`Multiplexer`s that are
 287     aggregated with a :class:`Decoder`, hierarchical CSR buses are useful for organizing
 288     a hierarchical design. If many peripherals are directly served by a single
 289     :class:`Multiplexer`, a very large amount of ports will connect the peripheral registers with
 290     the decoder, and the cost of decoding logic would not be attributed to specific peripherals.
 291     With a decoder, only five signals per peripheral will be used, and the logic could be kept
 292     together with the peripheral.
 293
 294     Parameters
 295     ----------
 296     addr_width : int
 297         Address width. See :class:`Interface`.
 298     data_width : int
 299         Data width. See :class:`Interface`.
 300     alignment : int
 301         Window alignment. See :class:`Interface`.
 302
 303     Attributes
 304     ----------
 305     bus : :class:`Interface`
 306         CSR bus providing access to subordinate buses.
 307     """
 308     def __init__(self, *, addr_width, data_width, alignment=0):
 309         self.bus   = Interface(addr_width=addr_width, data_width=data_width, alignment=alignment,
 310                                name="csr")
 311         self._map  = self.bus.memory_map
 312         self._subs = dict()
 313
 314     def align_to(self, alignment):
 315         """Align the implicit address of the next window.
 316
 317         See :meth:`MemoryMap.align_to` for details.
 318         """
 319         return self._map.align_to(alignment)
 320
 321     def add(self, sub_bus, *, addr=None):
 322         """Add a window to a subordinate bus.
 323
 324         See :meth:`MemoryMap.add_resource` for details.
 325         """
 326         if not isinstance(sub_bus, Interface):
 327             raise TypeError("Subordinate bus must be an instance of csr.Interface, not {!r}"
 328                             .format(sub_bus))
 329         if sub_bus.data_width != self.bus.data_width:
 330             raise ValueError("Subordinate bus has data width {}, which is not the same as "
 331                              "multiplexer data width {}"
 332                              .format(sub_bus.data_width, self.bus.data_width))
 333         self._subs[sub_bus.memory_map] = sub_bus
 334         return self._map.add_window(sub_bus.memory_map, addr=addr)
 335
 336     def elaborate(self, platform):
 337         m = Module()
 338
 339         # See Multiplexer.elaborate above.
 340         r_data_fanin = 0
 341
 342         with m.Switch(self.bus.addr):
 343             for sub_map, sub_pat in self._map.window_patterns():
 344                 sub_bus = self._subs[sub_map]
 345                 m.d.comb += sub_bus.addr.eq(self.bus.addr[:sub_bus.addr_width])
 346
 347                 # The CSR bus interface is defined to output zero when idle, allowing us to avoid
 348                 # adding a multiplexer here.
 349                 r_data_fanin |= sub_bus.r_data
 350                 m.d.comb += sub_bus.w_data.eq(self.bus.w_data)
 351
 352                 with m.Case(sub_pat):
 353                     m.d.comb += sub_bus.r_stb.eq(self.bus.r_stb)
 354                     m.d.comb += sub_bus.w_stb.eq(self.bus.w_stb)
 355
 356         m.d.comb += self.bus.r_data.eq(r_data_fanin)
 357
 358         return m