csr.py

#
# This file is part of LiteX.
#
# Copyright (c) 2015 Sebastien Bourdeauducq <sb@m-labs.hk>
# Copyright (c) 2015-2019 Florent Kermarrec <florent@enjoy-digital.fr>
# Copyright (c) 2016-2019 Tim 'mithro' Ansell <me@mith.ro>
# Copyright (c) 2019 Sean Cross <sean@xobs.io>
# SPDX-License-Identifier: BSD-2-Clause


"""
Configuration and Status Registers
**********************************

The lowest-level description of a register is provided by the ``CSR`` class,
which maps to the value at a single address on the target bus. Also provided
are helper classes for dealing with values larger than the CSR buses data
width.

 * ``CSRConstant``, for constant values.
 * ``CSRStatus``,   for providing information to the CPU.
 * ``CSRStorage``,  for allowing control via the CPU.

Generating register banks
=========================
A module can provide bus-independent CSRs by implementing a ``get_csrs`` method
that returns a list of instances of the classes described above.

Similarly, bus-independent memories can be returned as a list by a
``get_memories`` method.

To avoid listing those manually, a module can inherit from the ``AutoCSR``
class, which provides ``get_csrs`` and ``get_memories`` methods that scan for
CSR and memory attributes and return their list.
"""

from enum import IntEnum

from migen import *
from migen.util.misc import xdir
from migen.fhdl.tracer import get_obj_var_name

# Helpers ------------------------------------------------------------------------------------------

def _check_csr_location(n):
    if n is None:
        return
    if not isinstance(n, int):
        raise ValueError("CSR location should be an integer.")
    if n < 0:
        raise ValueError("CSR location should be non-negative.")

# CSRBase ------------------------------------------------------------------------------------------

class _CSRBase(DUID):
    def __init__(self, size, name, n=None):
        DUID.__init__(self)
        _check_csr_location(n)
        self.n     = n
        self.fixed = n is not None
        self.size = size
        self.name = get_obj_var_name(name)
        if self.name is None:
            raise ValueError("Cannot extract CSR name from code, need to specify.")
# CSRConstant --------------------------------------------------------------------------------------

class CSRConstant(DUID):
    """Register which contains a constant value.

    Useful for providing information on how a HDL was instantiated to firmware
    running on the device.
    """

    def __init__(self, value, bits_sign=None, name=None, n=None):
        DUID.__init__(self)
        _check_csr_location(n)
        self.n        = n
        self.fixed    = n is not None
        self.value    = Constant(value, bits_sign)
        self.name     = get_obj_var_name(name)
        self.constant = value
        if self.name is None:
            raise ValueError("Cannot extract CSR name from code, need to specify.")

    def read(self):
        """Read method for simulation."""
        yield
        return self.constant

# CSR ----------------------------------------------------------------------------------------------

class CSR(_CSRBase):
    """Basic CSR register.

    Parameters
    ----------
    size : int
        Size of the CSR register in bits.
        Must be less than CSR bus width!

    name : string
        Provide (or override the name) of the CSR register.

    Attributes
    ----------
    wr_data : Signal(size), out
        Contains the data written from the bus interface.
        ``wr_data`` is only valid when ``wr_stb`` is high.

    wr_stb : Signal(), out
        The strobe signal for ``wr_data``.
        It is active for one cycle, after or during a write from the bus.

    rd_data : Signal(size), in
        The value to be read from the bus.
        Must be provided at all times.

    rd_stb : Signal(), out
        The strobe signal for ``rd_data``.
        It is active for one cycle, after or during a read from the bus.

    r/re/w/we : Signal(), compatibility aliases
        Historical names kept for compatibility:
        ``r``/``re`` alias ``wr_data``/``wr_stb`` and
        ``w``/``we`` alias ``rd_data``/``rd_stb``.
    """

    def __init__(self, size=1, name=None, n=None):
        _CSRBase.__init__(self, size, name, n)
        self.wr_stb  = Signal(name=self.name + "_re")
        self.wr_data = Signal(self.size, name=self.name + "_r")
        self.rd_stb  = Signal(name=self.name + "_we")
        self.rd_data = Signal(self.size, name=self.name + "_w")

        # Compatibility aliases.
        self.re = self.wr_stb
        self.r  = self.wr_data
        self.we = self.rd_stb
        self.w  = self.rd_data

    def read(self):
        """Read method for simulation."""
        yield self.rd_stb.eq(1)
        value = (yield self.rd_data)
        yield
        yield self.rd_stb.eq(0)
        return value

    def write(self, value):
        """Write method for simulation."""
        yield self.wr_data.eq(value)
        yield self.wr_stb.eq(1)
        yield
        yield self.wr_stb.eq(0)


class CSRGap(_CSRBase):
    """Reserve one or more locations in a fixed CSR bank layout.

    When provided, ``n`` is the first reserved CSR index in the bank. Without
    ``n``, the gap is inserted at its natural declaration position. ``name`` is
    used as the generated CSR name prefix, while ``name_start`` controls the
    numeric suffix. Set ``name_start`` to ``None`` to use ``name`` as an exact
    name for a single-location gap.
    """

    def __init__(self, count=1, name="reserved", n=None, name_start=0):
        if count < 1:
            raise ValueError("CSRGap count must be >= 1.")
        if name_start is None and count != 1:
            raise ValueError("CSRGap name_start=None is only valid for a single-location gap.")
        _CSRBase.__init__(self, 0, name, n)
        self.count      = count
        self.name_start = name_start

    def get_name(self, index):
        if index < 0 or index >= self.count:
            raise ValueError(f"CSRGap index {index} outside gap size {self.count}.")
        if self.name_start is None:
            return self.name
        return f"{self.name}{self.name_start + index}"

    def read(self):
        yield
        return 0

    def write(self, value):
        yield


def _expand_csr_gap(csr_gap):
    return [CSR(name=csr_gap.get_name(i)) for i in range(csr_gap.count)]


class _CompoundCSR(_CSRBase, Module):
    def __init__(self, size, name, n=None):
        _CSRBase.__init__(self, size, name, n)
        self.simple_csrs = []

    def get_simple_csrs(self):
        if not self.finalized:
            raise FinalizeError
        return self.simple_csrs

    def do_finalize(self, busword):
        raise NotImplementedError

# CSRAccess ----------------------------------------------------------------------------------------

class CSRAccess(IntEnum):
    WriteOnly = 0
    ReadOnly  = 1
    ReadWrite = 2

# CSRField -----------------------------------------------------------------------------------------

class CSRField(Signal):
    """CSR Field.

    Parameters / Attributes
    -----------------------
    name : string
        Name of the CSR field.

    size : int
        Size of the CSR field in bits.

    offset : int (optional)
        Offset of the CSR field on the CSR register in bits.

    reset: int (optional)
        Reset value of the CSR field.

    description: string (optional)
        Description of the CSR Field (can be used to document the code and/or to be reused by tools
        to create the documentation).

    pulse: boolean (optional)
        Field value is only valid for one cycle when set to True. Only valid for 1-bit fields.

    access: enum (optional)
        Access type of the CSR field.

    values: list (optional)
        A list of supported values.
        If this is specified, a table will be generated containing the values in the specified order.
        The `value` must be an integer in order to allow for automatic constant generation in an IDE,
        except "do not care" bits are allowed.
        In the three-tuple variation, the middle value represents an enum value that can be displayed
        instead of the value.
                    [
                        ("0b0000", "disable the timer"),
                        ("0b0001", "slow", "slow timer"),
                        ("0b1xxx", "fast timer"),
                    ]
    """

    def __init__(self, name, size=1, offset=None, reset=0, description=None, pulse=False, access=None, values=None):
        assert access is None or (access in CSRAccess.__members__.values())
        self.name        = name
        self.size        = size
        self.offset      = offset
        self.reset_value = reset
        self.description = description
        self.access      = access
        self.pulse       = pulse
        self.values      = values
        Signal.__init__(self, size, name=name, reset=reset)


class CSRFieldAggregate:
    """CSR Field Aggregate."""

    def __init__(self, fields, access):
        self.check_names(fields)
        self.check_ordering_overlap(fields)
        self.fields = fields
        for field in fields:
            if field.access is None:
                field.access = access
            elif access == CSRAccess.ReadOnly:
                assert not field.pulse
                assert field.access == CSRAccess.ReadOnly
            elif access == CSRAccess.ReadWrite:
                assert field.access in [CSRAccess.ReadWrite, CSRAccess.WriteOnly]
                if field.pulse:
                    field.access = CSRAccess.WriteOnly
            setattr(self, field.name, field)

    @staticmethod
    def check_names(fields):
        names = []
        for field in fields:
            if field.name in names:
                raise ValueError("CSRField \"{}\" name is already used in CSR register".format(field.name))
            else:
                names.append(field.name)

    @staticmethod
    def check_ordering_overlap(fields):
        offset = 0
        for field in fields:
            if field.offset is not None:
                if field.offset < offset:
                    raise ValueError("CSRField ordering/overlap issue on \"{}\" field".format(field.name))
                offset = field.offset
            else:
                field.offset = offset
            offset += field.size

    def get_size(self):
        return self.fields[-1].offset + self.fields[-1].size

    def get_reset(self):
        reset = 0
        for field in self.fields:
            reset |= (field.reset_value << field.offset)
        return reset

# CSRStatus ----------------------------------------------------------------------------------------

class CSRStatus(_CompoundCSR):
    """Status Register.

    The ``CSRStatus`` class is meant to be used as a status register that is read-only from the CPU.

    The user design is expected to drive its ``status`` signal.

    The advantage of using ``CSRStatus`` instead of using ``CSR`` and driving ``w`` is that the
    width of ``CSRStatus`` can be arbitrary.

    Status registers larger than the bus word width are automatically broken down into several
    ``CSR`` registers to span several addresses.

    *Be careful, though:* the atomicity of reads is not guaranteed.

    Parameters
    ----------
    size : int
        Size of the CSR register in bits.
        Can be bigger than the CSR bus width.

    reset : string
        Value of the register after reset.

    name : string
        Provide (or override the name) of the ``CSRStatus`` register.

    Attributes
    ----------
    status : Signal(size), in
        The value of the CSRStatus register.
    """

    def __init__(self, size=1, reset=0, fields=[], name=None, description=None, read_only=True, n=None):
        if fields != []:
            self.fields = CSRFieldAggregate(fields, CSRAccess.ReadOnly)
            size  = self.fields.get_size()
            reset = self.fields.get_reset()
        _CompoundCSR.__init__(self, size, name, n)
        self.description = description
        self.read_only   = read_only
        self.status      = Signal(self.size, reset=reset)
        self.rd_stb      = Signal()
        self.wr_stb      = Signal()
        self.we          = self.rd_stb
        self.re          = self.wr_stb
        if not read_only:
            self.wr_data = Signal(self.size)
            self.r       = self.wr_data
        for field in fields:
            self.comb += self.status[field.offset:field.offset + field.size].eq(getattr(self.fields, field.name))

    def do_finalize(self, busword, ordering):
        nwords = (self.size + busword - 1)//busword
        for i in reversed(range(nwords)) if ordering == "big" else range(nwords):
            nbits = min(self.size - i*busword, busword)
            sc    = CSR(nbits, self.name + str(i) if nwords > 1 else self.name)
            self.comb += sc.rd_data.eq(self.status[i*busword:i*busword+nbits])
            self.simple_csrs.append(sc)
            if not self.read_only:
                lo = i*busword
                hi = lo+nbits
                self.sync += If(sc.wr_stb, self.wr_data[lo:hi].eq(sc.wr_data))
        self.comb += self.rd_stb.eq(sc.rd_stb)
        self.sync += self.wr_stb.eq(sc.wr_stb)

    def read(self):
        """Read method for simulation."""
        yield self.rd_stb.eq(1)
        if hasattr(self, "fields"):
            # In standalone simulation, CSRStatus is commonly used as a plain
            # CSR object rather than as a submodule, so pack the live fields
            # directly instead of relying on this module's internal comb logic.
            value = 0
            for field in [*self.fields.fields]:
                value |= (yield getattr(self.fields, field.name)) << field.offset
        else:
            value = (yield self.status)
        yield
        yield self.rd_stb.eq(0)
        return value

# CSRStorage ---------------------------------------------------------------------------------------

class CSRStorage(_CompoundCSR):
    """Control Register.

    The ``CSRStorage`` class provides a memory location that can be read and written by the CPU, and read and optionally written by the design.

    It can span several CSR addresses.

    Parameters
    ----------
    size : int
        Size of the CSR register in bits. Can be bigger than the CSR bus width.

    reset : string
        Value of the register after reset.

    reset_less : bool
        If `True`, do not generate reset logic for CSRStorage.

    atomic_write : bool
        Provide an mechanism for atomic CPU writes is provided. When enabled, writes to the first
        CSR addresses go to a back-buffer whose contents are atomically copied to the main buffer
        when the last address is written.

    write_from_dev : bool
        Allow the design to update the CSRStorage value. *Warning*: The atomicity of reads by the
         CPU is not guaranteed.

    name : string
        Provide (or override the name) of the ``CSRStatus`` register.

    Attributes
    ----------
    storage : Signal(size), out
        Signal providing the value of the ``CSRStorage`` object.

    wr_stb : Signal(), in
        The strobe signal indicating a write to the ``CSRStorage`` register from the CPU. It is active
        for one cycle, after or during a write from the bus.

    re : Signal(), in
        Compatibility alias for ``wr_stb``.

    we : Signal(), out
        The strobe signal to write to the ``CSRStorage`` register from the logic. Only available when
        ``write_from_dev == True``


    dat_w : Signal(), out
        The write data to write to the ``CSRStorage`` register from the logic. Only available when
        ``write_from_dev == True``
    """

    def __init__(self, size=1, reset=0, reset_less=False, fields=[], atomic_write=False, write_from_dev=False, name=None, description=None, n=None):
        if fields != []:
            self.fields = CSRFieldAggregate(fields, CSRAccess.ReadWrite)
            size  = self.fields.get_size()
            reset = self.fields.get_reset()
        _CompoundCSR.__init__(self, size, name, n)
        self.description  = description
        self.storage      = Signal(self.size, reset=reset, reset_less=reset_less)
        self.atomic_write = atomic_write
        self.wr_stb       = Signal()
        self.re           = self.wr_stb
        if write_from_dev:
            self.we    = Signal()
            self.dat_w = Signal(self.size)
            self.sync += If(self.we, self.storage.eq(self.dat_w))
        for field in [*fields]:
            field_assign = getattr(self.fields, field.name).eq(self.storage[field.offset:field.offset + field.size])
            if field.pulse:
                self.comb += If(self.wr_stb, field_assign)
            else:
                self.comb += field_assign

    def do_finalize(self, busword, ordering):
        nwords = (self.size + busword - 1)//busword
        # The CPU writes ascending addresses: with big ordering, word 0 (LSBs) is at the highest
        # address and thus written last; with little ordering, word nwords-1 (MSBs) is written
        # last. Commit the storage atomically on that last-written word.
        commit_word = 0 if (ordering == "big") else (nwords - 1)
        if nwords > 1 and self.atomic_write:
            # The backstore holds all the words but the commit one.
            backstore_width = {
                "big"    : self.size - busword,         # Words 1..nwords-1.
                "little" : (nwords - 1)*busword,        # Words 0..nwords-2.
            }[ordering]
            backstore = Signal(backstore_width, name=self.name + "_backstore")
        for i in reversed(range(nwords)) if ordering == "big" else range(nwords):
            nbits = min(self.size - i*busword, busword)
            sc    = CSR(nbits, self.name + str(i) if nwords > 1 else self.name)
            self.simple_csrs.append(sc)
            lo = i*busword
            hi = lo+nbits
            # read
            self.comb += sc.rd_data.eq(self.storage[lo:hi])
            # write
            if nwords > 1 and self.atomic_write:
                if i != commit_word:
                    backstore_lo = lo - (busword if ordering == "big" else 0)
                    backstore_hi = hi - (busword if ordering == "big" else 0)
                    self.sync += If(sc.wr_stb,
                        backstore[backstore_lo:backstore_hi].eq(sc.wr_data))
                else:
                    commit_value = {
                        "big"    : Cat(sc.wr_data, backstore),
                        "little" : Cat(backstore, sc.wr_data),
                    }[ordering]
                    self.sync += If(sc.wr_stb, self.storage.eq(commit_value))
            else:
                self.sync += If(sc.wr_stb, self.storage[lo:hi].eq(sc.wr_data))
        self.sync += self.wr_stb.eq(sc.wr_stb)

    def read(self):
        """Read method for simulation.

        Side effects: none (asynchronous)."""
        return (yield self.storage)

    def write(self, value):
        """Write method for simulation.

        Side effects: synchronous advances simulation clk by one tick."""
        if bits_for(value) > self.size:
            raise ValueError(f"value {value} exceeds range of {self.size} bit CSR {self.name}.")

        yield self.storage.eq(value)
        yield self.wr_stb.eq(1)
        if hasattr(self, "fields"):
            for field in [*self.fields.fields]:
                yield getattr(self.fields, field.name).eq((value >> field.offset) & (2**field.size -1))
        yield
        yield self.wr_stb.eq(0)
        if hasattr(self, "fields"):
            for field in [*self.fields.fields]:
                if field.pulse:
                    yield getattr(self.fields, field.name).eq(0)

# AutoCSR & Helpers --------------------------------------------------------------------------------

def csrprefix(prefix, csrs, done):
    for csr in csrs:
        if csr.duid not in done:
            csr.name = prefix + csr.name
            done.add(csr.duid)


def memprefix(prefix, memories, done):
    for memory in memories:
        if memory.duid not in done:
            memory.name_override = prefix + memory.name_override
            done.add(memory.duid)

def _sort_gathered_items(items):

    # Create list of variable items and sort it by DUID.
    # --------------------------------------------------
    variable_items = []
    for item in items:
        if not item.fixed:
            variable_items.append(item)
    variable_items = sorted(variable_items, key=lambda x: x.duid)

    # Create list of fixed items:
    # ---------------------------
    fixed_items = []
    for item in items:
        if item.fixed:
            fixed_items.append(item)

    # Determine items length.
    # -----------------------
    # Set to length of provided items after expanding gaps.
    items_length = 0
    for item in items:
        items_length += item.count if isinstance(item, CSRGap) else 1

    # Eventually extend with fixed items:
    for item in fixed_items:
        item_count = item.count if isinstance(item, CSRGap) else 1
        if (item.n + item_count) > items_length:
            items_length = item.n + item_count

    # Create list of sorted items:
    # ----------------------------

    # Create empty list.
    sorted_items = [None for _ in range(items_length)]

    # Fill fixed items.
    for item in fixed_items:
        if isinstance(item, CSRGap):
            for i, csr in enumerate(_expand_csr_gap(item)):
                location = item.n + i
                if sorted_items[location] is not None:
                    csr0 = item.get_name(i)
                    csr1 = sorted_items[location].name
                    raise ValueError(f"CSR conflict on location {location} between {csr0} and {csr1}.")
                sorted_items[location] = csr
            continue

        if sorted_items[item.n] is not None:
            csr0 = item.name
            csr1 = sorted_items[item.n].name
            raise ValueError(f"CSR conflict on location {item.n} between {csr0} and {csr1}.")
        sorted_items[item.n] = item

    # Fill variable items in empty locations.
    while len(variable_items):
        item = variable_items.pop(0)
        expanded_items = _expand_csr_gap(item) if isinstance(item, CSRGap) else [item]
        for expanded_item in expanded_items:
            for i in range(items_length):
                if sorted_items[i] is None:
                    sorted_items[i] = expanded_item
                    break
            else:
                raise ValueError(f"No free CSR location for {item.name}.")

    # Fill remaining location with reserved CSR.
    for i in range(items_length):
        if sorted_items[i] is None:
            sorted_items[i] = CSR(name=f"reserved{i}")


    # Verify all locations are filled.
    assert None not in sorted_items

    # Return.
    return sorted_items

def _make_gatherer(method, cls, prefix_cb, sort_cb=None):
    def gatherer(self, sort=False):
        try:
            exclude = self.autocsr_exclude
        except AttributeError:
            exclude = {}
        try:
            prefixed = self.__prefixed
        except AttributeError:
            prefixed = self.__prefixed = set()
        r = []
        for k, v in xdir(self, True):
            if k not in exclude:
                if isinstance(v, cls):
                    r.append(v)
                elif hasattr(v, method) and callable(getattr(v, method)):
                    items = getattr(v, method)()
                    prefix_cb(k + "_", items, prefixed)
                    r += items
        r = sorted(r, key=lambda x: x.duid)
        if sort and sort_cb is not None:
            r = sort_cb(r)
        return r
    return gatherer


class AutoCSR:
    """MixIn to provide bus independent access to CSR registers.

    A module can inherit from the ``AutoCSR`` class, which provides ``get_csrs``, ``get_memories``
    and ``get_constants`` methods that scan for CSR and memory attributes and return their list.

    If the module has child objects that implement ``get_csrs``, ``get_memories`` or ``get_constants``,
    they will be called by the``AutoCSR`` methods and their CSR and memories added to the lists returned,
    with the child objects' names as prefixes.
    """
    get_memories  = _make_gatherer(method="get_memories",  cls=Memory,      prefix_cb=memprefix)
    get_csrs      = _make_gatherer(
        method    = "get_csrs",
        cls       = _CSRBase,
        prefix_cb = csrprefix,
        sort_cb   = _sort_gathered_items,
    )
    get_constants = _make_gatherer(method="get_constants", cls=CSRConstant, prefix_cb=csrprefix)


class GenericBank(Module):
    def __init__(self, description, busword, ordering="big"):
        assert ordering in ["big", "little"]
        # Turn description into simple CSRs and claim ownership of compound CSR modules
        self.simple_csrs = []
        for c in description:
            if isinstance(c, CSRGap):
                for csr in _expand_csr_gap(c):
                    assert csr.size <= busword
                    self.simple_csrs.append(csr)
            elif isinstance(c, CSR):
                assert c.size <= busword
                self.simple_csrs.append(c)
            elif hasattr(c, "finalize"):
                c.finalize(busword, ordering)
                self.simple_csrs += c.get_simple_csrs()
                self.submodules  += c