Skip to content

S
Simple PCIe FMC carrier SPEC
Commit 3b053ebe authored by Federico Vaga's avatar Federico Vaga
Browse files
Options

doc: add PySPEC documentation 

Signed-off-by: Federico Vaga's avatarFederico Vaga <federico.vaga@cern.ch>
parent 3bbec72a
Hide whitespace changes
Inline Side-by-side
Showing with 121 additions and 21 deletions
doc/conf.py
View file @ 3b053ebe
...@@ -12,9 +12,9 @@ ...@@ -12,9 +12,9 @@
# add these directories to sys.path here. If the directory is relative to the # 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. # documentation root, use os.path.abspath to make it absolute, like shown here.
# #
# import os import os
# import sys import sys
# sys.path.insert(0, os.path.abspath('.')) sys.path.insert(0, os.path.abspath('../software/PySPEC/PySPEC'))
# -- Project information ----------------------------------------------------- # -- Project information -----------------------------------------------------
...@@ -39,7 +39,8 @@ release = 'v1.4' ...@@ -39,7 +39,8 @@ release = 'v1.4'
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones. # ones.
extensions = [ extensions = [
] 'sphinx.ext.autodoc'
]
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates'] templates_path = ['_templates']
...@@ -171,3 +172,7 @@ epub_title = project ...@@ -171,3 +172,7 @@ epub_title = project
# A list of files that should not be packed into the epub file. # A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html'] epub_exclude_files = ['search.html']
autodoc_default_options = {
'member-order': 'bysource',
}
doc/index.rst
View file @ 3b053ebe
...@@ -27,6 +27,7 @@ You can clone the GIT project with the following command:: ...@@ -27,6 +27,7 @@ You can clone the GIT project with the following command::
hdl-spec-base hdl-spec-base
sw-driver sw-driver
sw-python
.. _`Open HardWare Repository`: https://ohwr.org/ .. _`Open HardWare Repository`: https://ohwr.org/
.. _`SPEC project`: https://ohwr.org/project/spec .. _`SPEC project`: https://ohwr.org/project/spec
doc/sw-python.rst 0 → 100644
View file @ 3b053ebe
..
SPDX-License-Identifier: CC-BY-SA-4.0
SPDX-FileCopyrightText: 2019-2020 CERN
.. _spec_python:
SPEC Python: PySPEC
===================
.. autoclass:: PySPEC.PySPEC
:members:
software/PySPEC/PySPEC/PySPEC.py
View file @ 3b053ebe
...@@ -5,24 +5,107 @@ ...@@ -5,24 +5,107 @@
SPDX-License-Identifier: LGPL-3.0-or-later SPDX-License-Identifier: LGPL-3.0-or-later
SPDX-FileCopyrightText: 2020 CERN (home.cern) SPDX-FileCopyrightText: 2020 CERN (home.cern)
""" """
import os import os
from contextlib import contextmanager from contextlib import contextmanager
class PySPEC: class PySPEC:
"""
This class gives access to SPEC features.
"""
#: SPEC DDR size
DDR_SIZE = 256 * 1024 * 1024 DDR_SIZE = 256 * 1024 * 1024
#: SPEC DDR access alignment
DDR_ALIGN = 4 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: 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): 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): 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): def read(self, offset, size):
""" """
Trigger a *device to memory* DMA transfer 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) self.__seek(offset)
data = [] data = []
...@@ -32,7 +115,12 @@ class PySPEC: ...@@ -32,7 +115,12 @@ class PySPEC:
def write(self, offset, data): 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) self.__seek(offset)
start = 0 start = 0
...@@ -41,17 +129,10 @@ class PySPEC: ...@@ -41,17 +129,10 @@ class PySPEC:
return start return start
def __seek(self, offset): def __seek(self, offset):
self.dma_file.seek(offset) """
Change DDR 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))
@contextmanager :var offset: offset within the DDR
def dma(self): :raise OSError: if lseek(2) fails or the driver
spec_dma = self.PySPECDMA(self) """
try: self.dma_file.seek(offset)
yield spec_dma
finally:
spec_dma.close()
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment