nmigen/lib/io.py

   1 from .. import *
   2 from ..hdl.rec import *
   3
   4
   5 __all__ = ["pin_layout", "Pin"]
   6
   7
   8 def pin_layout(width, dir, xdr=0):
   9     """
  10     Layout of the platform interface of a pin or several pins, which may be used inside
  11     user-defined records.
  12
  13     See :class:`Pin` for details.
  14     """
  15     if not isinstance(width, int) or width < 1:
  16         raise TypeError("Width must be a positive integer, not {!r}"
  17                         .format(width))
  18     if dir not in ("i", "o", "oe", "io"):
  19         raise TypeError("Direction must be one of \"i\", \"o\", \"io\", or \"oe\", not {!r}"""
  20                         .format(dir))
  21     if not isinstance(xdr, int) or xdr < 0:
  22         raise TypeError("Gearing ratio must be a non-negative integer, not {!r}"
  23                         .format(xdr))
  24
  25     fields = []
  26     if dir in ("i", "io"):
  27         if xdr > 0:
  28             fields.append(("i_clk", 1))
  29         if xdr in (0, 1):
  30             fields.append(("i", width))
  31         else:
  32             for n in range(xdr):
  33                 fields.append(("i{}".format(n), width))
  34     if dir in ("o", "oe", "io"):
  35         if xdr > 0:
  36             fields.append(("o_clk", 1))
  37         if xdr in (0, 1):
  38             fields.append(("o", width))
  39         else:
  40             for n in range(xdr):
  41                 fields.append(("o{}".format(n), width))
  42     if dir in ("oe", "io"):
  43         fields.append(("oe", 1))
  44     return Layout(fields)
  45
  46
  47 class Pin(Record):
  48     """
  49     An interface to an I/O buffer or a group of them that provides uniform access to input, output,
  50     or tristate buffers that may include a 1:n gearbox. (A 1:2 gearbox is typically called "DDR".)
  51
  52     A :class:`Pin` is identical to a :class:`Record` that uses the corresponding :meth:`pin_layout`
  53     except that it allos accessing the parameters like ``width`` as attributes. It is legal to use
  54     a plain :class:`Record` anywhere a :class:`Pin` is used, provided that these attributes are
  55     not necessary.
  56
  57     Parameters
  58     ----------
  59     width : int
  60         Width of the ``i``/``iN`` and ``o``/``oN`` signals.
  61     dir : ``"i"``, ``"o"``, ``"io"``, ``"oe"``
  62         Direction of the buffers. If ``"i"`` is specified, only the ``i``/``iN`` signals are
  63         present. If ``"o"`` is specified, only the ``o``/``oN`` signals are present. If ``"oe"`` is
  64         specified, the ``o``/``oN`` signals are present, and an ``oe`` signal is present.
  65         If ``"io"`` is specified, both the ``i``/``iN`` and ``o``/``oN`` signals are present, and
  66         an ``oe`` signal is present.
  67     xdr : int
  68         Gearbox ratio. If equal to 0, the I/O buffer is combinatorial, and only ``i``/``o``
  69         signals are present. If equal to 1, the I/O buffer is SDR, and only ``i``/``o`` signals are
  70         present. If greater than 1, the I/O buffer includes a gearbox, and ``iN``/``oN`` signals
  71         are present instead, where ``N in range(0, N)``. For example, if ``xdr=2``, the I/O buffer
  72         is DDR; the signal ``i0`` reflects the value at the rising edge, and the signal ``i1``
  73         reflects the value at the falling edge.
  74     name : str
  75         Name of the underlying record.
  76
  77     Attributes
  78     ----------
  79     i_clk:
  80         I/O buffer input clock. Synchronizes `i*`. Present if ``xdr`` is nonzero.
  81     i : Signal, out
  82         I/O buffer input, without gearing. Present if ``dir="i"`` or ``dir="io"``, and ``xdr`` is
  83         equal to 0 or 1.
  84     i0, i1, ... : Signal, out
  85         I/O buffer inputs, with gearing. Present if ``dir="i"`` or ``dir="io"``, and ``xdr`` is
  86         greater than 1.
  87     o_clk:
  88         I/O buffer output clock. Synchronizes `o*`, including `oe`. Present if ``xdr`` is nonzero.
  89     o : Signal, in
  90         I/O buffer output, without gearing. Present if ``dir="o"`` or ``dir="io"``, and ``xdr`` is
  91         equal to 0 or 1.
  92     o0, o1, ... : Signal, in
  93         I/O buffer outputs, with gearing. Present if ``dir="o"`` or ``dir="io"``, and ``xdr`` is
  94         greater than 1.
  95     oe : Signal, in
  96         I/O buffer output enable. Present if ``dir="io"`` or ``dir="oe"``. Buffers generally
  97         cannot change direction more than once per cycle, so at most one output enable signal
  98         is present.
  99     """
 100     def __init__(self, width, dir, *, xdr=0, name=None, src_loc_at=0):
 101         self.width = width
 102         self.dir   = dir
 103         self.xdr   = xdr
 104
 105         super().__init__(pin_layout(self.width, self.dir, self.xdr),
 106                          name=name, src_loc_at=src_loc_at + 1)