doc: add PySPEC documentation

Signed-off-by: Federico Vaga <federico.vaga@cern.ch>

doc: add PySPEC documentation
Signed-off-by: Federico Vaga <federico.vaga@cern.ch>
3b053ebe · Federico Vaga · 3bbec72a · 3b053ebe · 3b053ebe · 3b053ebe
Commit 3b053ebe authored Jun 30, 2020 by Federico Vaga
Hide whitespace changes
Inline Side-by-side

Showing with 121 additions and 21 deletions

conf.py doc/conf.py +9 -4

index.rst doc/index.rst +1 -0

sw-python.rst doc/sw-python.rst +13 -0

PySPEC.py software/PySPEC/PySPEC/PySPEC.py +98 -17

No files found.
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -12,9 +12,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../software/PySPEC/PySPEC'))


 # -- Project information -----------------------------------------------------
@@ -39,7 +39,8 @@ release = 'v1.4'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-]
+    'sphinx.ext.autodoc'
+    ]

 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -171,3 +172,7 @@ epub_title = project

 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ['search.html']
+
+autodoc_default_options = {
+    'member-order': 'bysource',
+}
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -27,6 +27,7 @@ You can clone the GIT project with the following command::

   hdl-spec-base
   sw-driver
+   sw-python

 .. _`Open HardWare Repository`: https://ohwr.org/
 .. _`SPEC project`: https://ohwr.org/project/spec
--- a/doc/sw-python.rst
+++ b/doc/sw-python.rst
+..
+  SPDX-License-Identifier: CC-BY-SA-4.0
+  SPDX-FileCopyrightText: 2019-2020 CERN
+
+.. _spec_python:
+
+SPEC Python: PySPEC
+===================
+
+
+
+.. autoclass:: PySPEC.PySPEC
+   :members:
--- a/software/PySPEC/PySPEC/PySPEC.py
+++ b/software/PySPEC/PySPEC/PySPEC.py
@@ -5,24 +5,107 @@
 SPDX-License-Identifier: LGPL-3.0-or-later
 SPDX-FileCopyrightText: 2020 CERN  (home.cern)
 """
+
 import os
 from contextlib import contextmanager

 class PySPEC:
+    """
+    This class gives access to SPEC features.
+    """
+
+    #: SPEC DDR size
    DDR_SIZE = 256 * 1024 * 1024
+    #: SPEC DDR access alignment
    DDR_ALIGN = 4

+    def __init__(self, pci_id):
+        self.pci_id = pci_id
+        self.debugfs =  "/sys/kernel/debug/0000:{:s}".format(self.pci_id)
+        self.debugfs_fpga = os.path.join(self.debugfs, "spec-0000:{:s}".format(self.pci_id))
+
+    @contextmanager
+    def dma(self):
+        """
+        Create a DMA context from which users can do DMA
+        transfers. Within this context the user can use
+        PySPECDMA.read() and PySPECDMA.write(). Here an example.
+
+        >>> from PySPEC import PySPEC
+        >>> spec = PySPEC("06:00.0")
+        >>> with spec.dma() as dma:
+        >>>     cnt = dma.write(0, b"\x00" * 16)
+        >>>     buffer = dma.read(0, 16)
+
+        Which is equivalent to:
+
+        >>> from PySPEC import PySPEC
+        >>> spec = PySPEC("06:00.0")
+        >>> spec_dma = PySPEC.PySPECDMA(spec)
+        >>> spec_dma.open()
+        >>> cnt = spec_dma.write(0, b"\x00" * 16)
+        >>> buffer = spec_dma.read(0, 16)
+        >>> spec_dma.close()
+        """
+        spec_dma = self.PySPECDMA(self)
+        spec_dma.open()
+        try:
+            yield spec_dma
+        finally:
+            spec_dma.close()
+
    class PySPECDMA:
+        """
+        This class wraps DMA features in a single object.
+
+        The SPEC has
+        only one DMA channel. On request() the user will get exclusive
+        access. The user must release() the DMA channel as soon as
+        possible to let other users or drivers to access it. For this reason,
+        avoid to use this class directly. Instead, use the DMA context
+        from the PySPEC class which is less error prone.
+
+        >>> from PySPEC import PySPEC
+        >>> spec = PySPEC("06:00.0")
+        >>> with spec.dma() as dma:
+        >>>     cnt = dma.write(0, b"\x00" * 16)
+        >>>     buffer = dma.read(0, 16)
+        >>> print(buffer)
+        """
+
        def __init__(self, spec):
-            self.dma_file = open(os.path.join(spec.debugfs_fpga, "dma"),
-                                 "rb+", buffering=0)
+            """
+            Create a new instance

+            :var spec: a valid PySPEC instance
+            """
+            self.spec = spec
+
+        def open(self):
+            """
+            Open a DMA file descriptor
+
+            :raise OSError: if the open(2) or the driver fails
+            """
+            self.dma_file = open(os.path.join(self.spec.debugfs_fpga, "dma"),
+                                 "rb+", buffering=0)
        def close(self):
-            self.dma_file.close()
+            """
+            Close the DMA file descriptor
+
+            :raise OSError: if the close(2) or the driver fails
+            """
+            if hasattr(self, "dma_file"):
+                self.dma_file.close()

        def read(self, offset, size):
            """
            Trigger a *device to memory* DMA transfer
+
+            :var offset: offset within the DDR
+            :var size: number of bytes to be transferred
+            :return: the data transfered as bytes() array
+            :raise OSError: if the read(2) or the driver fails
            """
            self.__seek(offset)
            data = []
@@ -32,7 +115,12 @@ class PySPEC:

        def write(self, offset, data):
            """
-            Trigger a *device to memory* DMA transfer
+            Trigger a *memory to device* DMA transfer
+
+            :var offset: offset within the DDR
+            :var size: number of bytes to be transferred
+            :return: the number of transfered bytes
+            :raise OSError: if the write(2) or the driver fails
            """
            self.__seek(offset)
            start = 0
@@ -41,17 +129,10 @@ class PySPEC:
            return start

        def __seek(self, offset):
-            self.dma_file.seek(offset)
-
-    def __init__(self, pci_id):
-        self.pci_id = pci_id
-        self.debugfs =  "/sys/kernel/debug/0000:{:s}".format(self.pci_id)
-        self.debugfs_fpga = os.path.join(self.debugfs, "spec-0000:{:s}".format(self.pci_id))
+            """
+            Change DDR offset

-    @contextmanager
-    def dma(self):
-        spec_dma = self.PySPECDMA(self)
-        try:
-            yield spec_dma
-        finally:
-            spec_dma.close()
+            :var offset: offset within the DDR
+            :raise OSError: if lseek(2) fails or the driver
+            """
+            self.dma_file.seek(offset)