# 
# ATCACommon EPICS module
#
This module brings FPGA registers that are common to all ATCA-based IOC
applications:
    - Crossbar control
    - JESD configurations
    - Scope configuration

***************************************************************
* 1) Building the IOC application with the ATCACommon module *
***************************************************************

1.1) configure/RELEASE
ATCA_COMMON_MODULE_VERSION=<module version>
ATCACOMMON=$(EPICS_MODULES)/ATCACommon/$(ATCACOMMON_MODULE_VERSION)

1.2) configure/CONFIG_SITE
# ATCA COMMON API
COMMONATCA_PACKAGE_NAME=atca/commonATCA
COMMONATCA_VERSION=<package version>
COMMONATCA_TOP=$(PACKAGE_SITE_TOP)/$(COMMONATCA_PACKAGE_NAME)/$(COMMONATCA_VERSION)
COMMONATCA_LIB=$(COMMONATCA_TOP)/$(PKG_ARCH)/lib
COMMONATCA_INCLUDE=$(COMMONATCA_TOP)/$(PKG_ARCH)/include
 
1.3) src/Makefile
USR_INCLUDES += -I$(COMMONATCA_INCLUDE)
commonATCA_DIR = $(COMMONATCA_LIB)
USR_LIBS_Linux += commonATCA
<app>_DBD += ATCACommon.dbd
<app>_DBD += crossbarControl.dbd
<app>_LIBS += ATCACommon
 
1.4.a) Db/Makefile
You need to add the following db files

# ATCA common
DB_INSTALLS += $(ATCACOMMON)/db/crossbarCtrl.db
DB_INSTALLS += $(ATCACOMMON)/db/ATCACommon.db
DB_INSTALLS += $(ATCACOMMON)/db/Stream.db


1.5) st.cmd
# Don't use this before cpswLoadYamlFile()
# crossbarControlAsynDriverConfigure(Asyn port name, yaml path)
crossbarControlAsynDriverConfigure("crossbar", "mmio/AmcCarrierCore/AxiSy56040")
# Command to access common platform FPGA registers
# cpswATCACommonAsynDriverConfigure(Asyn port name, yaml path, named root (optional))
cpswATCACommonAsynDriverConfigure("atca", "mmio", "")

1.5a) Simple instantiation of scope (one configuration fits all channels of an AMC)

# Command to access common platform ATCA DAqMux waveforms. Use the command once per AMC card.
# scopeAsynDriverConfigure (
#    Asyn port name (must be different from previous one), 
#    scope index,
#    channel types (all channels will have this single type initial configuration),
#    An optional STRING number of samples. If not passed the default is used = 4096 @ 16-bit, 2048 @ 32-bit , 1024 @ 64-bit )

scopeAsynDriverConfigure("atca_str0", 0, "float64")
scopeAsynDriverConfigure("atca_str1", 1, "int16")

OR (not default number of samples used)

scopeAsynDriverConfigure("atca_str0", 0, "float64", "8192")
scopeAsynDriverConfigure("atca_str1", 1, "int16", "8192")

Note that the channel configuration can be modified dynamically later in runtime.

1.5b) Advanced instantiation of scope (individual initial configuration for each channel of an AMC)
 
# Command to access common platform ATCA DAqMux waveforms. Use the command once per AMC card.
# scopeAdvancedAsynDriverConfigure (
#    Asyn port name (must be different from previous one), 
#    scope index,
#    channel types,
#    An optional STRING number of samples. If not passed the default is used = 4096 @ 16-bit, 2048 @ 32-bit , 1024 @ 64-bit )

scopeAdvancedAsynDriverConfigure("atca_str0", 0, "int16", "int32", "int16", "float64")
scopeAdvancedAsynDriverConfigure("atca_str1", 1, "int16", "int16", "uint16", "float32")

OR (not default number of samples used)

scopeAdvancedAsynDriverConfigure("atca_str0", 0, "int16", "int32", "int16", "float64", "8192")
scopeAdvancedAsynDriverConfigure("atca_str1", 1, "int16", "int16", "uint16", "float32", "8192")

Note that the channel configuration can be modified dynamically later in runtime.

1.5c)

# ATCA common features

dbLoadRecords("db/ATCACommon.db", "DEV=${P},PORT=atca")
dbLoadRecords("db/crossbarCtrl.db", "DEV=$(P), PORT=crossbar")

Default number of elements is 4096 samples.
dbLoadRecords("db/Stream.db", "DEV=${P}:STR0, PORT=atca_str0, TSE=-2")
dbLoadRecords("db/Stream.db", "DEV=${P}:STR1, PORT=atca_str1, TSE=-2")

OR (not default number of samples used)

dbLoadRecords("db/Stream.db", "DEV=${P}:STR0, PORT=atca_str0, NELM=8192, TSE=-2")
dbLoadRecords("db/Stream.db", "DEV=${P}:STR1, PORT=atca_str1, NELM=8192, TSE=-2")


**************
* 2) Screens *
**************

Launch it through:
cd pydm
pydm -m "DEVICE=<record base name>" ATCACommon.ui &

example: pydm -m "DEVICE=EM1K0:GMD:HPS" ./ATCACommon.ui &

The main screen provides three buttons
1- Dual scope screen: allows the visualization and configuration of scope 0 and scope 1
2- JESD Diagnostics : opens some JESD diagnostics
3- Crossbar configuration : allows 4-input/4-output crossbar configuration

2.1) Dual scope screen

Generic user interfaces developed in PyDM are provided to the user to control the oscilloscope and enrich
the user’s seamless overall experience. The Scope standard interface using PyDM is in the Dual scope screen. The
ATCA Scope probes are configured dynamically by the user to probe up to four inputs of the ATCA ADC/DAC daughter
cards. The stream data type interpretation is also configured dynamically as well. The user can also specify a desired
sampling rate and the ATCA Scope will estimate the nearest possible sampling rate using the current sampling frequency,
and perform down-sampling to try to match that rate. If the user requires averaging to be applied when the channel is
down-sampled, then he would need to enable the averaging button for the corresponding channel. The averaging is done
over the number of samples that were dropped. The Scope trigger configurations and information screen contains:
• Trigger Count: the number of triggers that the Scope
received up to that point.
• Button Clear: clears Trigger Count.
• Button Trigger: induces a manual trigger event by clicking the trigger button.
  Buttons Auto-Re-arm and Arm Hardware Trig: if Auto Rearm is selected, every time the trigger event occurs,
  the next trigger will automatically be armed. If Disable is selected, the user needs to arm the trigger by clicking
  on the Arm trigger button and, after the trigger happens, select the Normal position of the button again.
• Button Cascaded Trigger: if Cascaded Trigger is enabled for Scope 1, it will trigger together with Scope 0
  and vice-versa.
• Timestamp (s:ns): shows seconds and nanoseconds for
  the last trigger.

2.2) JESD diagnostics
Shows some few JESD configurations and status

2.3) Crossbar configuration
Allows the user to choose the routing of the following destinations: RTM_OUT0, FPGA, Back plane, RTM_OUT1. 
The sources are: RTM_IN0, FPGA, Back plane, RTM_IN1


Firmware support

In order to get stream data from the scopes in firmware, the firmware 000TopLevel.yaml 
file must contain all the following instantiations with the exact naming as follows. 
Note that Stream0 - Stream3 belong to Scope 0, and Stream4 - Stream7 belong to Scope 1. 
You may instantiate only the streams of scope 0 or scope 1 or both.

stream: &stream
    SRP:
      protocolVersion: SRP_UDP_NONE
    UDP:
      port: *udpPortNumber1
      numRxThreads: 2
      threadPriority: *udpPri
    RSSI:
        <<: *rssiParams
        threadPriority: 81
        inpQueueDepth: 32
    depack:
      protocolVersion: *depacketizerProtocolVersion
    TDESTMux:
      TDEST: 0x80
      stripHeader: yes

# streams must be instantiated in the NetIODev
NetIODev: &BPMNetIODev
  ipAddr: 10.0.1.102
  class: NetIODev
  configPrio: 1
  children:
     Stream0:
       class: Field
       at:
         <<: *stream
         TDESTMux:
           TDEST: 0x80
     Stream1:
       class: Field
       at:
         <<: *stream
         TDESTMux:
           TDEST: 0x81
     Stream2:
       class: Field
       at:
         <<: *stream
         TDESTMux:
           TDEST: 0x82
     Stream3:
       class: Field
       at:
         <<: *stream
         TDESTMux:
           TDEST: 0x83
     Stream4:
       class: Field
       at:
         <<: *stream
         TDESTMux:
           TDEST: 0x84
     Stream5:
       class: Field
       at:
         <<: *stream
         TDESTMux:
           TDEST: 0x85
     Stream6:
       class: Field
       at:
         <<: *stream
         TDESTMux:
           TDEST: 0x86
     Stream7:
       class: Field
       at:
         <<: *stream
         TDESTMux:
           TDEST: 0x87