Adding Fifo Configuration support and adding new status's (#14)

* Support for Advanced FIFO Configurations with RIO 17.6

* Added quering the FPGA VI State with RIO 18.0

Author: mgumble

nifpga/nifpga.py

@@ -48,6 +48,95 @@ def _return_ctype(self):
         return _datatype_ctype[self]
 
 
+class FifoPropertyType(Enum):
+    """ Types of FIFO Properties, intended to abstract away the C Type. """
+    I32 = 1
+    U32 = 2
+    I64 = 3
+    U64 = 4
+    Ptr = 5
+
+    def __str__(self):
+        return self.name
+
+    def _return_ctype(self):
+        """ Returns the associated ctype of a given property type. """
+        _propertyType_ctype = {
+            FifoPropertyType.I32: ctypes.c_int32,
+            FifoPropertyType.U32: ctypes.c_uint32,
+            FifoPropertyType.I64: ctypes.c_int64,
+            FifoPropertyType.U64: ctypes.c_uint64,
+            FifoPropertyType.Ptr: ctypes.c_void_p
+        }
+        return _propertyType_ctype[self]
+
+
+class FifoProperty(Enum):
+    BytesPerElement = 1  # U32
+    BufferAllocationGranularityElements = 2  # U32
+    BufferSizeElements = 3  # U64
+    MirroredElements = 4  # U64
+    DmaBufferType = 5  # I32
+    DmaBuffer = 6  # Ptr
+    FlowControl = 7  # I32
+
+    def __str__(self):
+        return self.name
+
+
+class FlowControl(Enum):
+    """ When flow control is disabled, the FIFO no longer acts like a FIFO.
+    The FIFO will overwrite data in this mode. The FPGA fully controls when
+    data transfers. This can be useful when regenerating a waveform or when
+    you only care about the most recent data.
+    For Host to Target FIFOs, this only disables flow control when the entire FIFO
+    has been written once.
+    For Target to Host FIFOs, flow control is disabled on start and the FPGA can
+    begin writing then.
+    """
+    DisableFlowControl = 1
+    """ Default FIFO behavior. No data is lost, data only moves when there is
+    room for it.
+    """
+    EnableFlowControl = 2
+
+
+class DmaBufferType(Enum):
+    """ Allocated by RIO means the driver take the other properties and create
+    a buffer that meets their requirements.
+    """
+    AllocatedByRIO = 1
+    """ Allocated by User means you will allocate a buffer and set the DMA Buffer
+    property with your buffer. The driver will then use this buffer as the
+    underlying host memory in the FIFO.
+    """
+    AllocatedByUser = 2
+
+
+_fifo_properties_to_types = {
+    FifoProperty.BytesPerElement: FifoPropertyType.U32,
+    FifoProperty.BufferAllocationGranularityElements: FifoPropertyType.U32,
+    FifoProperty.BufferSizeElements: FifoPropertyType.U64,
+    FifoProperty.MirroredElements: FifoPropertyType.U64,
+    FifoProperty.DmaBufferType: FifoPropertyType.I32,
+    FifoProperty.DmaBuffer: FifoPropertyType.Ptr,
+    FifoProperty.FlowControl: FifoPropertyType.I32,
+}
+
+
+class FpgaViState(Enum):
+    """ The FPGA VI has either been downloaded and not run, or the VI was aborted
+    or reset. """
+    NotRunning = 0
+    """ An error has occurred. """
+    Invalid = 1
+    """ The FPGA VI is currently executing. """
+    Running = 2
+    """ The FPGA VI stopped normally.  This indicates it was not aborted or reset,
+    but instead reached the end of any loops it was executing and ended. """
+    NaturallyStopped = 3
+
+
 _SessionType = ctypes.c_uint32
 _IrqContextType = ctypes.c_void_p
 
@@ -244,6 +333,38 @@ def __init__(self):
                     NamedArgtype("inBufferSize", ctypes.c_size_t),
                     NamedArgtype("outBuffer", ctypes.c_void_p),
                     NamedArgtype("outBufferSize", ctypes.c_size_t),
+                ]),
+            LibraryFunctionInfo(
+                pretty_name="FindRegisterPrivate",
+                name_in_library="NiFpgaDll_FindRegisterPrivate",
+                named_argtypes=[
+                    NamedArgtype("session", _SessionType),
+                    NamedArgtype("name", ctypes.c_char_p),
+                    NamedArgtype("expectedType", ctypes.c_uint32),
+                    NamedArgtype("offset", ctypes.POINTER(ctypes.c_uint32)),
+                ]),
+            LibraryFunctionInfo(
+                pretty_name="FindFifoPrivate",
+                name_in_library="NiFpgaDll_FindFifoPrivate",
+                named_argtypes=[
+                    NamedArgtype("session", _SessionType),
+                    NamedArgtype("name", ctypes.c_char_p),
+                    NamedArgtype("expectedType", ctypes.c_uint32),
+                    NamedArgtype("fifoNumber", ctypes.POINTER(ctypes.c_uint32)),
+                ]),
+            LibraryFunctionInfo(
+                pretty_name="GetFpgaViState",
+                name_in_library="NiFpgaDll_GetFpgaViState",
+                named_argtypes=[
+                    NamedArgtype("session", _SessionType),
+                    NamedArgtype("state", ctypes.POINTER(ctypes.c_uint32)),
+                ]),
+            LibraryFunctionInfo(
+                pretty_name="CommitFifoConfiguration",
+                name_in_library="NiFpgaDll_CommitFifoConfiguration",
+                named_argtypes=[
+                    NamedArgtype("session", _SessionType),
+                    NamedArgtype("fifo", ctypes.c_uint32),
                 ])
         ]  # list of function_infos
 
@@ -331,6 +452,29 @@ def __init__(self):
                         NamedArgtype("elements remaining", ctypes.POINTER(ctypes.c_size_t)),
                     ]),
             ])  # end of library_function_infos.extend() call
+
+        for fifoPropertyType in FifoPropertyType:
+            type_ctype = fifoPropertyType._return_ctype()
+            library_function_infos.extend([
+                LibraryFunctionInfo(
+                    pretty_name="GetFifoProperty%s" % fifoPropertyType,
+                    name_in_library="NiFpgaDll_GetFifoProperty%s" % fifoPropertyType,
+                    named_argtypes=[
+                        NamedArgtype("session", _SessionType),
+                        NamedArgtype("fifo", ctypes.c_uint32),
+                        NamedArgtype("property", ctypes.c_uint32),
+                        NamedArgtype("value", ctypes.POINTER(type_ctype)),
+                    ]),
+                LibraryFunctionInfo(
+                    pretty_name="SetFifoProperty%s" % fifoPropertyType,
+                    name_in_library="NiFpgaDll_SetFifoProperty%s" % fifoPropertyType,
+                    named_argtypes=[
+                        NamedArgtype("session", _SessionType),
+                        NamedArgtype("fifo", ctypes.c_uint32),
+                        NamedArgtype("property", ctypes.c_uint32),
+                        NamedArgtype("value", type_ctype),
+                    ]),
+            ])
         try:
             super(_NiFpga, self).__init__(library_name="NiFpga",
                                           library_function_infos=library_function_infos)

nifpga/session.py

@@ -6,7 +6,9 @@
 
 from .nifpga import (_SessionType, _IrqContextType, _NiFpga, DataType,
                      OPEN_ATTRIBUTE_NO_RUN, RUN_ATTRIBUTE_WAIT_UNTIL_DONE,
-                     CLOSE_ATTRIBUTE_NO_RESET_IF_LAST_SESSION)
+                     CLOSE_ATTRIBUTE_NO_RESET_IF_LAST_SESSION, FifoProperty,
+                     _fifo_properties_to_types, FlowControl, DmaBufferType,
+                     FpgaViState)
 from .bitfile import Bitfile
 from .status import InvalidSessionError
 from collections import namedtuple
@@ -28,6 +30,7 @@ class Session(object):
 
         with Session(bitfile="myBitfilePath.lvbitx", resource="RIO0") as session:
             session.run()
+            FpgaAlreadyRunningWarning: pass
             session.download()
             session.abort()
             session.reset()
@@ -177,6 +180,13 @@ def reset(self):
         """ Resets the FPGA VI. """
         self._nifpga.Reset(self._session)
 
+    @property
+    def fpga_vi_state(self):
+        """ Returns the current state of the FPGA VI. """
+        state = ctypes.c_uint32()
+        self._nifpga.GetFpgaViState(self._session, state)
+        return FpgaViState(state.value)
+
     def _irq_ordinals_to_bitmask(self, ordinals):
         bitmask = 0
         for ordinal in ordinals:
@@ -580,6 +590,10 @@ def get_peer_to_peer_endpoint(self):
         self._nifpga.GetPeerToPeerFifoEndpoint(self._session, self._number, endpoint)
         return endpoint.value
 
+    def commit_configuration(self):
+        """ Resolves and Commits property changes made to the FIFO. """
+        self._nifpga.CommitFifoConfiguration(self._session, self._number)
+
     @property
     def name(self):
         """ Property of a Fifo that contains its name. """
@@ -589,3 +603,97 @@ def name(self):
     def datatype(self):
         """ Property of a Fifo that contains its datatype. """
         return self._datatype
+
+    def _get_fifo_property(self, prop):
+        prop_type = _fifo_properties_to_types[prop]
+        value = (prop_type._return_ctype())(0)
+        value_pointer = ctypes.pointer(value)
+        self._nifpga['GetFifoProperty%s' % prop_type](self._session, self._number, prop.value, value_pointer)
+        return value.value
+
+    def _set_fifo_property(self, prop, value):
+        prop_type = _fifo_properties_to_types[prop]
+        self._nifpga['SetFifoProperty%s' % prop_type](self._session, self._number, prop.value, value)
+
+    @property
+    def buffer_allocation_granularity(self):
+        """ The allocation granularity of the host memory part of a DMA FIFO.
+
+        By default this will usually be a page size, which is optimal for most
+        devices.  This property can be used to customize it.
+        """
+        return self._get_fifo_property(FifoProperty.BufferAllocationGranularityElements)
+
+    @buffer_allocation_granularity.setter
+    def buffer_allocation_granularity(self, value):
+        self._set_fifo_property(FifoProperty.BufferAllocationGranularityElements, value)
+
+    @property
+    def buffer_size(self):
+        """ The size in elements of the Host Memory part of a DMA FIFO. """
+        return self._get_fifo_property(FifoProperty.BufferSizeElements)
+
+    @buffer_size.setter
+    def buffer_size(self, value):
+        self._set_fifo_property(FifoProperty.BufferSizeElements, value)
+
+    @property
+    def _mirror_size(self):
+        """ The amount of elements in the Host Memory part of the DMA FIFO that
+        mirror elements at the beginning.
+
+        The Host Memory part of a DMA FIFO is a circular buffer.  This means that
+        when we hit the end of the buffer we have to deal with the logic of wrapping
+        around the buffer.  Mirrored elements are elements at the beginning of
+        the buffer that are mapped twice in memory to the end of the buffer.
+        Settings this value can allow us to avoid wrap arounds.
+
+        This is mostly useful when using our Zero Copy API.  Its not yet
+        supported in Python though, so this property is private.
+        """
+        return self._get_fifo_property(FifoProperty.MirroredElements)
+
+    @_mirror_size.setter
+    def _mirror_size(self, value):
+        self._set_fifo_property(FifoProperty.MirroredElements, value)
+
+    @property
+    def _dma_buffer_type(self):
+        return self._get_fifo_property(FifoProperty.DmaBufferType)
+
+    @_dma_buffer_type.setter
+    def _dma_buffer_type(self, value):
+        if not isinstance(value, DmaBufferType):
+            raise TypeError("_dma_buffer_type must be set to a nifpga.DmaBufferType")
+        self._set_fifo_property(FifoProperty.DmaBufferType, value.value)
+
+    @property
+    def _dma_buffer(self):
+        return self._get_fifo_property(FifoProperty.DmaBuffer)
+
+    @_dma_buffer.setter
+    def _dma_buffer(self, value):
+        self._set_fifo_property(FifoProperty.DmaBuffer, value)
+
+    @property
+    def flow_control(self):
+        """ Controls whether the FPGA will wait for the host when using FIFOs.
+
+        If flow control is disabled, the FPGA will have free reign to read or
+        write elements before the host is ready.  This means the FIFO no longer
+        acts in a First In First Out manner.
+
+        For Host To Target FIFOs, this feature is useful when you want to put
+        something like a waveform in a FIFO and let the FPGA continue reading
+        that waveform over and over without any involvement from the host.
+
+        For Target To Host FIFOs, this feature is useful when you only care
+        about the latest data and don't care about old data.
+        """
+        return self._get_fifo_property(FifoProperty.FlowControl)
+
+    @flow_control.setter
+    def flow_control(self, value):
+        if not isinstance(value, FlowControl):
+            raise TypeError("flow_control must be set to an nifpga.FlowControl")
+        self._set_fifo_property(FifoProperty.FlowControl, value.value)

nifpga/status.py

@@ -280,6 +280,7 @@ def __init__(self, code, function_name, argument_names, function_args):
     (-52007, "OperationTimedOut"),
     (-52008, "OSFault"),
     (-52010, "ResourceNotInitialized"),
+    (-52012, "EndOfData"),
     (-52013, "ObjectNameCollision"),
     (-61003, "FpgaAlreadyRunning"),
     (-61018, "DownloadError"),
@@ -311,19 +312,31 @@ def __init__(self, code, function_name, argument_names, function_args):
     (-63033, "AccessDenied"),
     (-63038, "HostVersionMismatch"),
     (-63040, "RpcConnectionError"),
+    (-63041, "RpcServerError"),
+    (-63042, "NetworkFault"),
     (-63043, "RpcSessionError"),
+    (-63044, "RpcServerMissing"),
+    (-63050, "TriggerReserved"),
+    (-63051, "TriggerNotReserved"),
     (-63080, "BufferInvalidSize"),
+    (-63081, "BufferNotAllocated"),
     (-63082, "FifoReserved"),
     (-63083, "FifoElementsCurrentlyAcquired"),
     (-63084, "MisalignedAccess"),
     (-63085, "ControlOrIndicatorTooLarge"),
+    (-63086, "OperationNotSupportedWhileStarted"),
+    (-63087, "TypesDoNotMatch"),
     (-63101, "BitfileReadError"),
     (-63106, "SignatureMismatch"),
     (-63107, "IncompatibleBitfile"),
     (-63150, "HardwareFault"),
     (-63170, "PowerShutdown"),
     (-63171, "ThermalShutdown"),
     (-63180, "InvalidAliasName"),
+    (-63181, "AliasNotFound"),
+    (-63182, "InvalidDeviceAccess"),
+    (-63183, "InvalidPort"),
+    (-63184, "ChildDeviceNotInserted"),
     (-63192, "InvalidResourceName"),
     (-63193, "FeatureNotSupported"),
     (-63194, "VersionMismatch"),