#
#    llrfHlsAsyn epics driver
#
1. configure/CONFIG_SITE

add LLRFHLS API as the folowings 
remarks) the version will varies depends on release

# LLRFHLS API
LLRFHLS_PACKAGE_NAME=rf/llrfHls
LLRFHLS_VERSION=llrfHls-git
LLRFHLS_TOP=$(PACKAGE_SITE_TOP)/$(LLRFHLS_PACKAGE_NAME)/$(LLRFHLS_VERSION)
LLRFHLS_LIB=$(LLRFHLS_TOP)/$(PKG_ARCH)/lib
LLRFHLS_INCLUDE=$(LLRFHLS_TOP)/$(PKG_ARCH)/include


2. configure/RELEASE.local

add LLRFHLSASYN module as the followings
remarks) the version will varies depends on release

LLRFHLSASYN_MODULE_VERSION=llrfHlsAsyn-git
LLRFHLSASYN=$(EPICS_MODULES)/llrfHlsAsyn/$(LLRFHLSASYN_MODULE_VERSION)


3. <application>/src/Makefile

add dbd and library for llrfHlsAsyn

<application_name>_DBD += llrfHlsAsynDriver.dbd
<application_name>_LIB += llrfHlsAsyn

add llrfHls API 

llrfHls_DIR = $(LLRFHLS_LIB)
USR_LIB_Linux += llrfHls


4. <application>/Db/Makefile

add database template for llrfHlsAsy

DB_INSTALLS += $(LLRFHLSASYN)/db/llrfHlsASyn.db



5. iocBoot/<ioc_name>/st.cmd

# driver configuration
#################################################################
#
# llrfHlsAsynDriverConfigure('port', 'register path', 'named_root')
#
# port           : port name for asynPort driver, should be matched with dbLoadRecords
# register path  : register path in hierarchy yaml, ex) mmio/AppTop/AppCore/Sysgen/LlrfFeedbackWrapper
# named_root     : optional for multi-root system, ioc engineer can skip it for a single root system

llrfHlsAsynDriverConfigure("llrfHls0", "mmio/AppTop/AppCore/Sysgen/LlrfFeedbackWrapper")



# database template
#################################################################
#
# dbLoadRecord("db/llrfHlsAsyn.db", "DEV=${IOC_NAME}:$(INST),PORT=$(LLRFHLS_PORT)")

dbLoadRecords("db/llrfHlsAsyn.db", "DEV=${IOC_NAME}:0,PORT=llrfHls0")


5. Permutation Index and Average Windows
   to complensate the cable delay varying across channels in XTCAV

The LLRF trigger serves as the pivotal point for the entire LLRF processing 
workflow, impacting various aspects such as the initiation of the average window, 
channel averaging, feedback loop, and RF signal generation. Unfortunately, our 
system lacks the flexibility to independently adjust the trigger delay 
for each individual channel.

In the context of the XTCAV system, we encounter notable differences 
in cable lengths across its channels. Consequently, the average window 
coincides with distinct portions of the RF pulse in the time domain 
due to these varying cable delay disparities. 
Given our inability to fine-tune the trigger delay on a per-channel basis, 
we find ourselves in need of employing different average windows 
for each channel in order to obtain an average phase/amplitude (or I/Q values) 
at the same location within the RF pulse.

Currently, our system employs three distinct windows, following this convention: 
the first window is designated for feedback purposes, while the next two windows 
are utilized for diagnostics. If we could manage the permutation of 
these three windows differently, we would be able to apply 
three distinct average windows based on the cable delay for each channel.

Hence, we propose the introduction of a permutation index for each channel, 
and the following outlines the rules governing this permutation process.

-----------  -----------------------  ----------------------------
                Average window
Permutation       Permutation
Index        (FB)->(Diag0)->(Diag1)   Remarks
-----------  -----------------------  ----------------------------
     0             (0)->(1)->(2)      default, backward compatible
     1             (1)->(2)->(0)
     2             (2)->(0)->(1)
-----------  -----------------------  ----------------------------


6. Internal Data Structure for Statistical data
index [0, 17]  -- statistics for virtual timeslot [00, 17]
index 18       -- statistics for NT (non-timeslot-aware)
index [19, 21] -- statistics for destinaitons:
                       19: destination 0    -- HXR
                       20: destination 1    -- SXR
                       21: destination 2    -- Spare