docs: move the generator details to doc/gen.md (and land #46/#48 on master)

.github/workflows/ci.yml

@@ -4,7 +4,12 @@ on: [push, pull_request]
 
 jobs:
   build:
+    name: test (py${{ matrix.python-version }})
     runs-on: ubuntu-22.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.12"]
     steps:
       # Checkout Repository
       - name: Checkout
@@ -15,10 +20,10 @@ jobs:
         run: |
           sudo apt-get install -y wget build-essential
 
-      - name: Set up Python 3.9
+      - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
         with:
-          python-version: "3.9"
+          python-version: ${{ matrix.python-version }}
           cache: "pip"
           cache-dependency-path: "setup.py"
 

README.md

@@ -36,6 +36,7 @@ PHY:
   - Xilinx Kintex-7 GTX (`GTXE2_CHANNEL`)
   - Xilinx UltraScale GTH (`GTHE3_CHANNEL`)
   - Xilinx UltraScale+ GTH/GTY (`GTHE4_CHANNEL`/`GTYE4_CHANNEL`, selected with `gt_type`; Artix UltraScale+ is GTH only)
+  - Lattice ECP5 SERDES (`DCUA`, Gen2 only, OOB generated/detected in fabric)
   - OOB, COMWAKE, COMINIT
   - ALIGN inserter/remover and bytes alignment on K28.5
   - 8B/10B encoding/decoding in transceiver
@@ -60,6 +61,7 @@ Core:
 
 Frontend:
   - Configurable crossbar (simply declare your crossbar and use crossbar.get_port() to add a new port!)
+  - Standalone Verilog core generator (`litesata_gen`) with native user ports and/or a Wishbone/AXI-Lite control bus + Wishbone DMA master
   - Ports arbitration transparent to the user
   - Synthesizable BIST
   - Striping module to segment data on multiple HDDs and increase write/read speed and capacity. (RAID0 equivalent)
@@ -73,12 +75,14 @@ LiteSATA is already used in commercial and open-source designs:
 
 [> Possible improvements
 ------------------------
-- add standardized interfaces (AXI, Avalon-ST)
+- add AXI-Stream user ports / AXI DMA master to the standalone core
+- add host-side link rate negotiation (Gen3 -> Gen2 -> Gen1 fallback)
+- add FLUSH CACHE / TRIM commands and 4Kn sector support
 - add NCQ support
 - add AES hardware encryption
 - add on-the-fly compression/decompression
-- add support for Altera PHYs.
-- add support for Lattice PHYs.
+- add support for Altera/Intel PHYs.
+- add ECP5 Gen1 (1.5Gbps) support and Linux integration.
 - add Zynq Linux drivers.
 - ... See below Support and consulting :)
 
@@ -87,10 +91,19 @@ enjoy-digital.fr.
 
 [> Getting started
 ------------------
-1. Install Python 3.7+ and FPGA vendor's development tools.
+1. Install Python 3.9+ and FPGA vendor's development tools.
 2. Install LiteX and the cores by following the LiteX's wiki [installation guide](https://github.com/enjoy-digital/litex/wiki/Installation).
 3. You can find examples of integration of the core with LiteX in LiteX-Boards and in the examples directory.
 
+[> Standalone core generation
+-----------------------------
+A standalone Verilog core (native streaming ports, or a Wishbone/AXI-Lite control bus with DMA) can
+be generated from a YAML description:
+```sh
+$ litesata_gen examples/artix7.yml
+```
+See [doc/gen.md](doc/gen.md) for the flavours, YAML keys and examples.
+
 [> Tests
 --------
 Unit tests are available in ./test/.

doc/gen.md

@@ -0,0 +1,36 @@
+# Standalone core generation
+
+LiteSATA is normally used as a Python package inside a LiteX SoC. For a traditional flow (no
+Migen/LiteX at build time, versioned/packaged core, ...), a standalone Verilog core can be generated
+from a YAML description with `litesata_gen` (`python3 -m litesata.gen`):
+```sh
+$ litesata_gen examples/artix7.yml [--output-dir build] [--name litesata_core]
+```
+The outputs are `build/gateware/litesata_core.v`, the Vivado constraints/`.tcl` and `build/csr.csv`
+(register map, for the control/DMA flavour).
+
+## YAML keys
+
+| Key              | Values                                                     | Default      |
+|------------------|------------------------------------------------------------|--------------|
+| `phy`            | `A7SATAPHY`, `K7SATAPHY`, `GTH3SATAPHY`, `GTH4SATAPHY`, `GTY4SATAPHY` | required |
+| `gen`            | `gen1`, `gen2`, `gen3` (fixed link rate)                   | required     |
+| `clk_freq`       | system clock frequency (Hz)                                | required     |
+| `data_width`     | PHY datapath width, 16 or 32                               | 16           |
+| `gt_type`        | `GTH`/`GTY` override (UltraScale+ only)                    | from `phy`   |
+| `core`           | `wishbone` or `axi-lite` control bus (CSRs at 0x00000000)  | none         |
+| `dma_data_width` | Wishbone DMA master width                                  | 32           |
+| `dma_mode`       | `read`, `write`, `read+write`                              | `read+write` |
+| `with_identify`, `with_bist`, `with_irq` | frontends/IRQ of the control/DMA flavour | True/False/True |
+| `user_ports`     | `{name: {"type": "native", "data_width": 32 or 64}}`       | none         |
+
+## PHYs and flavours
+
+PHY names map to transceivers: `A7SATAPHY` Artix-7 GTP, `K7SATAPHY` Kintex-7 GTX, `GTH3SATAPHY`
+UltraScale GTH, `GTH4SATAPHY` Artix/Kintex/Zynq UltraScale+ GTH, `GTY4SATAPHY` Kintex/Virtex
+UltraScale+ GTY. Without `core`, only native streaming ports are exposed (no CPU needed). With `core`,
+the control bus gives access to the PHY status, Identify, optional BIST and the Sector2Mem/Mem2Sector
+DMAs (which master the `wb_dma` bus), and `irq` signals DMA completion. The system clock must satisfy
+`clk_freq >= linerate / dma_data_width` for the DMA flavour (e.g. 75MHz for Gen3 on a 64-bit bus).
+Transceiver location and reference clock pin constraints are added by the integrator. See
+`examples/` for native and control/DMA configurations.

litesata/gen.py

@@ -83,8 +83,11 @@ def get_sata_ios():
 
 def get_ctrl_ios():
     return [
-        ("enable", 0, Pins(1)),
-        ("ready",  0, Pins(1)),
+        ("enable",     0, Pins(1)),
+        ("ready",      0, Pins(1)),
+        ("link_up",    0, Pins(1)), # Debounced link status.
+        ("connect",    0, Pins(1)), # Single-cycle pulse on link up.
+        ("disconnect", 0, Pins(1)), # Single-cycle pulse on (debounced) link down.
     ]
 
 def get_irq_ios():
@@ -165,6 +168,9 @@ def __init__(self, platform, core_config):
             with_csr   = bus_standard is not None)
         self.comb += self.sata_phy.enable.eq(platform.request("enable"))
         self.comb += platform.request("ready").eq(self.sata_phy.ready)
+        self.comb += platform.request("link_up").eq(self.sata_phy.link_up)
+        self.comb += platform.request("connect").eq(self.sata_phy.connect_irq)
+        self.comb += platform.request("disconnect").eq(self.sata_phy.disconnect_irq)
 
         if bus_standard is None:
             # Native core: SATA Core + Crossbar only -----------------------------------------------

litesata/phy/__init__.py

@@ -31,7 +31,7 @@ class LiteSATAPHY(LiteXModule):
     """
     def __init__(self, device, pads, gen, clk_freq, refclk=None, data_width=16,
                  qpll=None, gt_type="GTY", use_gtgrefclk=True, with_csr=True,
-                 dual=0, channel=0):
+                 dual=0, channel=0, link_down_timeout=100e-3):
         self.pads   = pads
         self.gen    = gen
         self.refclk = refclk
@@ -118,6 +118,13 @@ def __init__(self, device, pads, gen, clk_freq, refclk=None, data_width=16,
             self.comb += self.phy.serdes.init.rst.eq(~self.enable)
         self.comb += self.ready.eq(self.phy.ready & self.ctrl.ready)
 
+        # Link events.
+        # ------------
+        self.link_monitor   = LiteSATAPHYLinkMonitor(self.ready, down_cycles=int(link_down_timeout*clk_freq))
+        self.link_up        = self.link_monitor.link_up
+        self.connect_irq    = self.link_monitor.connect
+        self.disconnect_irq = self.link_monitor.disconnect
+
         # CSRs.
         # -----
         if with_csr:
@@ -142,6 +149,10 @@ def  add_csr(self):
                     ("``0b0``", "Ctrl/OOB not initialized."),
                     ("``0b1``", "Ctrl/OOB initialized and ready.")
             ]),
+            CSRField("link_up", size=1, values=[
+                    ("``0b0``", "Link down (debounced)."),
+                    ("``0b1``", "Link up.")
+            ]),
         ])
 
         self.comb += self.enable.eq(self._enable.storage)
@@ -156,3 +167,4 @@ def  add_csr(self):
             self.comb += self._status.fields.tx_ready.eq(self.phy.ready)
             self.comb += self._status.fields.rx_ready.eq(self.phy.ready)
         self.comb += self._status.fields.ctrl_ready.eq(self.ctrl.ready)
+        self.comb += self._status.fields.link_up.eq(self.link_up)

litesata/phy/ctrl.py

@@ -187,3 +187,34 @@ def __init__(self, trx, crg, clk_freq):
     def us(self, t):
         clk_period_us = 1e6/self.clk_freq
         return ceil(t/clk_period_us)
+
+# LiteSATAPHYLinkMonitor ---------------------------------------------------------------------------
+
+class LiteSATAPHYLinkMonitor(LiteXModule):
+    """Debounced link up/down events derived from the PHY ready signal.
+
+    link_up rises as soon as ready is asserted (ready already includes the controller's stability
+    time) and falls only once ready has stayed low for down_cycles, so the short re-initializations
+    performed by the controller (misalignment, idle retries) do not generate events while a device
+    unplug does. connect/disconnect are single-cycle pulses (EventSourcePulse compatible).
+    """
+    def __init__(self, ready, down_cycles):
+        self.link_up    = Signal()
+        self.connect    = Signal()
+        self.disconnect = Signal()
+
+        # # #
+
+        self.timer = timer = WaitTimer(down_cycles)
+        link_up_d = Signal()
+        self.comb += timer.wait.eq(~ready)
+        self.sync += [
+            If(ready,
+                self.link_up.eq(1)
+            ).Elif(timer.done,
+                self.link_up.eq(0)
+            ),
+            link_up_d.eq(self.link_up),
+            self.connect.eq(self.link_up & ~link_up_d),
+            self.disconnect.eq(~self.link_up & link_up_d),
+        ]

setup.py

@@ -19,7 +19,7 @@
     url                           = "http://enjoy-digital.fr",
     download_url                  = "https://github.com/enjoy-digital/litesata",
     license                       = "BSD-2-Clause",
-    python_requires               = "~=3.7",
+    python_requires               = ">=3.9",
     install_requires              = ["pyyaml", "litex"],
     extras_require                = {
         "develop": [

test/test_gen.py

@@ -107,6 +107,8 @@ def test_examples(self):
                 verilog, files = generate_example(name)
                 ports = re.findall(r"^\s*(?:input|output)\s+wire\s*(?:\[[^\]]*\])?\s*(\w+),?$", verilog, re.M)
                 self.assertIn(primitive, verilog)
+                for pad in ["enable", "ready", "link_up", "connect", "disconnect"]:
+                    self.assertIn(pad, ports)
                 self.assertIn("litesata_core.v", files)
                 self.assertIn("csr.csv", files)
                 # Native port: the sink data pad must drive the crossbar (it was left unconnected).

test/test_phy_ctrl.py

@@ -11,7 +11,7 @@
 from migen.sim import run_simulation
 
 from litesata.common import primitives
-from litesata.phy.ctrl import LiteSATAPHYCtrl
+from litesata.phy.ctrl import LiteSATAPHYCtrl, LiteSATAPHYLinkMonitor
 from litesata.phy.ecp5sataphy import ECP5LiteSATAPHYCtrl
 
 
@@ -116,5 +116,47 @@ def test_early_align_latch_is_opt_in(self):
         self.assertEqual(result["data"], primitives["ALIGN"])
 
 
+class TestPHYLinkMonitor(unittest.TestCase):
+    def test_link_events(self):
+        class DUT(Module):
+            def __init__(self):
+                self.ready = Signal()
+                self.submodules.monitor = LiteSATAPHYLinkMonitor(self.ready, down_cycles=16)
+
+        dut    = DUT()
+        events = []
+
+        def generator():
+            def drive(ready, cycles):
+                yield dut.ready.eq(ready)
+                for _ in range(cycles):
+                    yield
+                    if (yield dut.monitor.connect):
+                        events.append("connect")
+                    if (yield dut.monitor.disconnect):
+                        events.append("disconnect")
+
+            yield from drive(0, 4)
+            self.assertEqual(events, [])
+            # Ready: immediate link up + one connect pulse.
+            yield from drive(1, 4)
+            self.assertEqual((yield dut.monitor.link_up), 1)
+            self.assertEqual(events, ["connect"])
+            # Short drop (re-initialization): no event.
+            yield from drive(0, 8)
+            yield from drive(1, 4)
+            self.assertEqual((yield dut.monitor.link_up), 1)
+            self.assertEqual(events, ["connect"])
+            # Long drop (unplug): one disconnect pulse after the timeout.
+            yield from drive(0, 32)
+            self.assertEqual((yield dut.monitor.link_up), 0)
+            self.assertEqual(events, ["connect", "disconnect"])
+            # Back: one connect pulse.
+            yield from drive(1, 4)
+            self.assertEqual(events, ["connect", "disconnect", "connect"])
+
+        run_simulation(dut, generator())
+
+
 if __name__ == "__main__":
     unittest.main()