----------
tprPattern
----------

The tprPattern is an epics module which provides a standard PV interface
to set up soft event and monitoring timing pattern status for LCLS1.
This module works with TimingCore firmware, and it also provides 
evnet module compatible API and functions for TimingApi.

Note) it is an early day version of tprPattern, we provide event module compatible API,
and part of TimingApi whihc is BSA callback registration function.
All other functions in TimingApi will be implemented soon.

How to build an ioc with tprPattern module
------------------------------------------

1. The tprPattern requires hpsTpr API layer.
configure/CONFIG_SITE should have the followings for the hpsTpr API.

HPSTPR_PACKAGE_NAME=timing/hpsTpr
HPSTPR_VERSION=R1.0.2
HPSTPR_ARCH=$(LINUXRT_BUILDROOT_VERSION)-x86_64
HPSTPR=$(PACKAGE_AREA)/$(HPSTPR_PACKAGE_NAME)/$(HPSTPR_VERSION)/$(HPSTPR_ARCH)
HPSTPR_LIB     = $(HPSTPR)/lib
HPSTPR_INCLUDE = $(HPSTPR)/include

(The version number should be replaced with a proper version for your ioc.)


2. tprPattern module
configure/RELEASE should have the followings for tprPattern module.

TPRPATTERN_MODULE_VERSION=R1.0.0
TPRPATTERN=$(EPICS_MODULES)/tprPattern/$(TPRPATTERN_MODULE_VERSION)


3. Other module and API
the tprTrigger module assumes the following API and modules are included in the application.

asyn            R4.31-0.1.0
yamlLoader      R1.1.2
timingApi       R0.6

cpsw/framework  R3.6.4
yaml-cpp        yaml-cpp-0.5.3_boost-1.64.0
boost           1.64.0
hpsTpr          R1.0.2



4. How to build application binary

The Makefile in source directory should include the followings:

# DBD file for tprPattern
<your_application>_DBD += tprPatternAsynDriver.dbd

# Libarary for tprPattern
<your_application>_LIBS += tprPattern

# API for tprPattern
hpsTpr_DIR = $(HPSTPR_LIB)
<your_application>_LIBS += hpsTpr


The Makefile in Db directory need to install database template for tprPattern
as the followings:

# Install Database for tprPattern module
DB_INSTALLS += $(TPRPATTERN)/db/tprPattern.db

 
How to run ioc with tprPattern
-------------------------------

1. How to load database template for tprPattern

Macros for tprPattern.db

PORT      - port name for asyn port driver, tprPattern moudle has port name "pattern".
LOCA      - location (ex, LI24, IN20)
IOC_UNIT  - IOC name (ex, RF01, RF02)
INST      - instance number for mutiple TPR in an ioc


example)
dbLoadRecords("db/tprPattern.db", "LOCA=LI24,IOC_UNIT=RF02,INST=0,PORT=pattern")

it will make tprPattern PVs which have prefix "TPR:LI24:RF02:0:".


2. How to initialize the driver
The tprPattern assums yamlLoader driver already loaded up the register hierarchy as the followings:

cpswLoadYamlFile("000TopLevel.yaml", "NetIODev", "", "10.0.3.105")

(The yaml file path, register path and IP address can be different for specific application.) 

After loading the hierarchy, we can configure tprPattern driver with the following commands.

tprPatternAsynDriverConfigure(<asyn port name>, <path for AmcCarrierCore>, <path for timing stream>)

Hers is a typical example.
tprPatternAsynDriverConfigure("pattern", "mmio/AmcCarrierEmpty/AmcCarrierCore", "tstream")


3. Timing Stream

The tprPattern assumes, it receives LCLS1 timing pattern from UDP port 8197 in firmware side.
The UDP port should be described in yaml file.
The firmware assumes, it receives beacon packet periodically (less than 3 second interval) from software.
If firmware doesn't receive the packet, firmware stops to send stream, clean up destination information 
and wait request from another destination.
Thus, we need to pu "pollSec: 1" for the stream definiation in the yaml file.


4. Multiple Blades configuration and named_root

Multiple balde system have multiple root. We can identify the root via named_root.
The yamlLoader driver configuration command has an aadditional (optional argument) to specify the named_root.

tprPattern driver can choose a particular root path with describing the named_root (very last argument in the driver configuration command).
ex)
        cd  ${YAML_DIR0}
        cpswLoadYamlFile("000TopLevel.yaml", "NetIODev", "", "10.0.3.102", "root_slot2")
        cd  ${YAML_DIR1}
        cpswLoadYamlFile("000TopLevel.yaml", "NetIODev", "", "10.0.3.103", "root_slot3")
        cd  ${YAML_DIR2}
        cpswLoadYamlFile("000TopLevel.yaml", "NetIODev", "", "10.0.3.104", "root_slot4")

	tprPatternAsynDriverConfigure("pattern", "mmio/AmcCarrierEmpty/AmcCarrierCore", "tstream", "root_slot2")

Note) The tprPattern driver only allow a single instance in a system even the system has multiple blades. 
It is similar with multiple EVR in VME system, trigger functions allows to use all for EVRs in the system, 
but timing pattern is only work with a first EVR card.
We can use multiple tprPattern driver instaces but, we can use a single tprPattern driver instace.