Teledyne Digitizer Evaluation

    CBXFEL Digitizer Test Plan
    Chris Ford <caf@slac.stanford.edu>
    Nov 1, 2022

------- Phase 1 ---------------------------------------------------

Receive Teledyne documentation and software

Receive charge code

Work with Thuy to install digitizer and timing hardware in 2U crate
 - Building 034
 - Remote access
 - root or sudo access

------- Phase 2 ---------------------------------------------------

Verify basic compatibility with SLAC's Linux environment
 - Teledyne kernel module (insmod)
 - Teledyne library (build and run example C program)

Verify reading a DC voltage

------- Phase 3 ---------------------------------------------------

Connect SLAC trigger
Verify synchronous operation at 1 Hz
Verify synchronous operation at 120 Hz

    CBXFEL Digitizer Test Plan
    Chris Ford <caf@slac.stanford.edu>
    Nov 29, 2022

------- Phase 1 --(complete)---------------------------------------

Receive Teledyne documentation and software

Receive charge code

Work with Thuy to install digitizer and timing hardware in 2U crate
 - Building 034
 - Remote access
 - root or sudo access

Verify that card is recognized by Linux using lspci
(Note: we did this with 1U cpu and CentOS 7)

------- Phase 2 --(in progress)------------------------------------

Verify basic compatibility with SLAC's Linux environment
 - obtain GPL'd kernel module  (complete)
 - build kernel module in SLAC LinuxRT environment (in progress)
 - Teledyne kernel module: insmod
 - Teledyne library: build and run ADQAPI_simple_example.c

Verify reading a DC voltage

------- Phase 3 ---------------------------------------------------

Connect trigger to SLAC EVR (requires 2U cpu)

Verify synchronous operation at 1 Hz

Verify synchronous operation at 120 Hz

------- Open Issues -----------------------------------------------

1. Missing compatible power cable for 2U cpu
2. Teledyne library depends on libusb even though ADQ14 is pci

INSTALLATION
============
To install the SDK packages, enter the "packages" directory and find the linux
distribution and processor architecture you are using.  Specific instructions
for each distribution follows below.
After installing all necessary packages, reboot the system so that udev reads
the updated configuration and the driver loads.
**Note** In earlier versions there was a package called 'adqupdater' which is
now replaced with the 'adqtools' package.
Ubuntu and Debian
-----------------
Install delivered versions of our packages using:
    dpkg -i packagename
Use the following order:
 - spd-adq-pci-dkms (not needed for USB devices)
 - libadq0
 - adqtools
OpenSUSE and SUSE Linux Enterprise
----------------------------------
Install these packages using:
    zypper install packagename
Use the following order:
 - make
 - kernel-devel
 - kernel-source
 - gcc
The version of kernel-devel and kernel-source must match your current
kernel. Install delivered versions of our packages using:
    rpm -U packagename
Use the following order:
 - dkms
 - spd-adq-pci-dkms (not needed for USB devices)
 - libadq0
 - adqtools
OpenSUSE Leap 15.0 or later
---------------------------
Install these packages using:
    zypper install packagename
Use the following order:
 - make
 - kernel-devel
 - kernel-source
 - gcc
 - dkms
The version of kernel-devel and kernel-source must match your current
kernel. Install delivered versions of our packages using:
    rpm -U packagename
Use the following order:
 - spd-adq-pci-dkms (not needed for USB devices)
 - libadq0
 - adqtools
Fedora 19, 20 and 21
--------------------
Install the dkms package using:
    yum install dkms
Install delivered versions of our packages using:
    rpm -U packagename
Use the following order:
 - spd-adq-pci-dkms (not needed for USB devices)
 - libadq0
 - adqtools
Fedora 22 and higher
--------------------
Install the dkms package
    dnf install packagename
Install delivered versions of our packages using:
    dnf install packagename
Use the following order:
 - spd-adq-pci-dkms (not needed for USB devices)
 - libadq0
 - adqtools
CentOS / Red Hat Enterprise Linux / Scientific Linux
----------------------------------------------------
**Note** For RHEL6, use CentOS6 packages.
Install these packages using:
    yum install packagename
Use the following order
 - make
 - kernel-devel
 - gcc
The version of kernel-devel must match your current kernel.
Install delivered versions of our packages using:
    rpm -U packagename
Use the following order:
 - dkms
 - spd-adq-pci-dkms (not needed for USB devices)
 - libadq0
 - adqtools
Device access permissions
=========================
ADQ devices show up as `/dev/adq_pcie_` and `/dev/adq_usb_`, the default udev
setting is to add read/write access to the user group "adq".  The libadq0
package will create a user group called "adq" if that group doesn't already
exist in the system.  To be able to access the devices, in order to add your
user to the "adq" group use the command:
    usermod -a -G adq username
The user will have to logout and login again for the changes to take effect.
Kernel module version compatibility
===================================
The PCIe kernel module supports kernel versions from 2.6.32 and forward, however
kernel version 3.8.0 or newer is recommended.
The PCIe kernel module is not signed and thus will not load if your kernel uses
"secure boot".  If "secure boot" is enabled, it will need to be disabled before
the kernel module can be loaded. Refer to your distribution documentation on
how to do this.
API user guide
==============
The API user guide is included as a .pdf document in the "doc" directory. All
API functions are described there.
Example code
============
Example code for different languages can be found in the "examples" directory.
C/C++ examples
--------------
C/C++ example code is compiled using Make by going to the directory with the
Makefile and running "make". To setup include paths and defines for the
compiler "pkg-config" is used in the C/C++ examples. If not already installed,
pkg-config can be installed using the appropriate distribution package tools.
Python examples
---------------
The Python examples are written for Python 3. They use the "ctypes" module to
call ADQAPI functions and convert Python data structures to the appropriate
format.