From 7e30fda871fdb44edf6dc58fe35b2f1bfafa1220 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C4=99drzej=20Boczar?= <jboczar@antmicro.com>
Date: Mon, 26 Oct 2020 16:36:53 +0100
Subject: [PATCH] Add DFIInjector CSRs documentation

---
 litedram/dfii.py | 42 +++++++++++++++++++++++++-----------------
 1 file changed, 25 insertions(+), 17 deletions(-)

diff --git a/litedram/dfii.py b/litedram/dfii.py
index c73b62c..e61e75f 100644
--- a/litedram/dfii.py
+++ b/litedram/dfii.py
@@ -14,21 +14,29 @@ from litex.soc.interconnect.csr import *
 
 class PhaseInjector(Module, AutoCSR):
     def __init__(self, phase):
-        self._command       = CSRStorage(6)  # cs, we, cas, ras, wren, rden
-        self._command_issue = CSR()
-        self._address       = CSRStorage(len(phase.address), reset_less=True)
-        self._baddress      = CSRStorage(len(phase.bank),    reset_less=True)
-        self._wrdata        = CSRStorage(len(phase.wrdata),  reset_less=True)
-        self._rddata        = CSRStatus(len(phase.rddata))
+        self._command       = CSRStorage(fields=[
+            CSRField("cs",   size=1, description="DFI chip select bus"),
+            CSRField("we",   size=1, description="DFI write enable bus"),
+            CSRField("cas",  size=1, description="DFI column address strobe bus"),
+            CSRField("ras",  size=1, description="DFI row address strobe bus"),
+            CSRField("wren", size=1, description="DFI write data enable bus"),
+            CSRField("rden", size=1, description="DFI read data enable bus"),
+        ], description="Control DFI signals on a single phase")
+
+        self._command_issue = CSR() # description="The command gets commited on a write to this register"
+        self._address       = CSRStorage(len(phase.address), reset_less=True,  description="DFI address bus")
+        self._baddress      = CSRStorage(len(phase.bank),    reset_less=True,  description="DFI bank address bus")
+        self._wrdata        = CSRStorage(len(phase.wrdata),  reset_less=True,  description="DFI write data bus")
+        self._rddata        = CSRStatus(len(phase.rddata), description="DFI read data bus")
 
         # # #
 
         self.comb += [
             If(self._command_issue.re,
-                phase.cs_n.eq(Replicate(~self._command.storage[0], len(phase.cs_n))),
-                phase.we_n.eq(~self._command.storage[1]),
-                phase.cas_n.eq(~self._command.storage[2]),
-                phase.ras_n.eq(~self._command.storage[3])
+                phase.cs_n.eq(Replicate(~self._command.fields.cs, len(phase.cs_n))),
+                phase.we_n.eq(~self._command.fields.we),
+                phase.cas_n.eq(~self._command.fields.cas),
+                phase.ras_n.eq(~self._command.fields.ras)
             ).Else(
                 phase.cs_n.eq(Replicate(1, len(phase.cs_n))),
                 phase.we_n.eq(1),
@@ -37,8 +45,8 @@ class PhaseInjector(Module, AutoCSR):
             ),
             phase.address.eq(self._address.storage),
             phase.bank.eq(self._baddress.storage),
-            phase.wrdata_en.eq(self._command_issue.re & self._command.storage[4]),
-            phase.rddata_en.eq(self._command_issue.re & self._command.storage[5]),
+            phase.wrdata_en.eq(self._command_issue.re & self._command.fields.wren),
+            phase.rddata_en.eq(self._command_issue.re & self._command.fields.rden),
             phase.wrdata.eq(self._wrdata.storage),
             phase.wrdata_mask.eq(0)
         ]
@@ -58,12 +66,12 @@ class DFIInjector(Module, AutoCSR):
         self._control = CSRStorage(fields=[
             CSRField("sel",     size=1, values=[
                 ("``0b0``", "Software (CPU) control."),
-                ("``0b1`",  "Hardware control (default)."),
+                ("``0b1``", "Hardware control (default)."),
             ], reset=0b1), # Defaults to HW control.
-            CSRField("cke",     size=1),
-            CSRField("odt",     size=1),
-            CSRField("reset_n", size=1),
-        ])
+            CSRField("cke",     size=1, description="DFI clock enable bus"),
+            CSRField("odt",     size=1, description="DFI on-die termination bus"),
+            CSRField("reset_n", size=1, description="DFI clock reset bus"),
+        ], description="Control DFI signals common to all phases")
 
         for n, phase in enumerate(csr_dfi.phases):
             setattr(self.submodules, "pi" + str(n), PhaseInjector(phase))