Notes
=================

1. IOMMU Incompatability
------------------------

The BitFlow Linux Driver is not presently compatible with desktop IOMMU. Some newer systems have VT-d (virtual iommu) capability.  This can cause issues with the BitFlow driver's DMA memory access. The symptom is kernel log messages associated with BitFlow DMA and referencing DRHD and/or DMAR. When IOMMU is turned on, the acquired images will appear all black since the DMA engine is failing.

IOMMU can be explicitly disabled on Intel systems with the following kernel boot argument:

  .. code-block:: console

    intel_iommu=off

IOMMU can be explicitly disabled on AMD systems with the following kernel boot argument:

  .. code-block:: console

    amd_iommu=off

2. /proc/bitflowNN
---------------------

All BitFlow frame grabbers (VFG) generate a file in /proc. 

The file is named "**/proc/bitflowNN**", where NN is the /dev/videoNN assigned by video4linux: 

/proc/bitflow00 for /dev/video0,
.
.
.
/proc/bitflow12 for /dev/video12, etc.

The /proc/bitflowNN files are read only and contain status of the BitFlow hardware and driver state.

.. note::  The /proc/bitflowNN data related to CON registers contains the value of the last read or write to these registers -- reading the /proc information does not access the hardware registers but instead accesses the "shadow" copy of the last value read or written to the registers.

3. CIexample -I
----------------------

To read all CON registers and display the content (plus all other available driver information) use:

        .. code-block:: console
        
          $ CIexample -I

The output of this function and the content of the system log (/var/log/messages or /var/log/syslog) provides much valuable information for diagnosing operating issues with the BitFlow framegrabbers.

4. Read Register Value
------------------------------

To read the immediate value of a CON register use the CIcmdln tool:

        .. code-block:: console

          $ CIcmdln -o <VFGndx> 0 -r <VFGndx> <n> -c <VFGndx>

where,

- VFGdx is "N" of **/dev/videoN** of the desired frame grabber
- <n> specifies the register name (for e.g. n = 60 for CON60)

5. CIcmdln -i
----------------

To determine the desired VFG index use the CIcmdLn tool:
            
        .. code-block:: console

          $  CIcmdln -i

this displays all the BitFlow frame grabbers installed.

6. CUDA GPUDirect
--------------------

To build the BitFlow module with GPUDirect compatability:

- The PC must be running 64b linux
- NVIDIA CUDA SDK must be installed
- NVIDIA driver interface must be present
- The BitFlow driver must be built w/Makefile_gpud:
  
    .. code-block:: console
    
      $ ./install
      $ cd drv

    Modify the Makefile_gpud for proper NPATH2BUILD and NV_INSTALL_PATH

    .. code-block:: console

      $ cp Makefile_gpud Makefile
      $ make -C /lib/modules/`uname -r`/build M=`pwd`
      $ sudo modprobe videodev
      $ sudo insmod bitflow.ko

There are two examples:

  - **CIsimpleGPUD.cu**      camera data DMA->GPU memory and pixels displayed
  - **CIsimpleCUDAGPUD.cu**  camera data DMA->GPU; GPU kernel clamps pix b4 display

  The CUDA examples must be built w/Makefile_GPUD
        
  .. code-block:: console
    
    $ ./install
    $ cd src

  modify Makefile_GPUD for proper CUDA_PATH, BF_CUDA_INC, and BF_CUDA_LIB
              
  .. code-block:: console
    
    $ make -f Makefile_GPUD

  To test with the synthetic camera data:

  .. code-block:: console
    
    $ ./CIsimpleGPUD -x vfgNdx
    $ ./CIsimpleCUDAGPUD -x vfgNdx -c 100 200

7. AMD DirectGMA
--------------------

To build the BitFlow module with DirectGMA compatability:

- The PC must be running 64b linux
- The AMD APP SDK must be installed
- The AMD DirectGMA SDK must be installed
- The AMD driver must be installed
- Test your fglrx/DGMA install by successfully running clinfo and aticonfig. Do not attempt to run BitFlow DGMA before those two tools run w/o error.

There are two examples:

  - CIsimpleDGMA.c     camera data DMA->GPU memory and are displayed
  - CIsimpleCLDGMA.c   camera data DMA->GPU; GPU kernel clamps pixels b4 display

  The DGMA examples must be built w/Makefile_DGMA
        
  .. code-block:: console
    
    $ ./install
    $ cd src

  Modifiy Makefile_DGMA for proper path to AMD include and lib

  .. code-block:: console

    $ make -f Makefile_DGMA

  To test with synthetic camera data:

  .. code-block:: console
    
    $ ./CIsimpleGPUD -x vfgNdx
    $ ./CIsimpleCUDAGPUD -x vfgNdx -c 100 200

8. Changelog
---------------
.. toctree::
   :maxdepth: 2

   changelog