Migration from previous FESA3 versions

FESA3 5.0.1/5.0.2 7.0.0

FESA3 v5.0.1 and v5.0.2 are equivalent as regards migration.

Basic migration steps

To migrate existing FESA software from the previous FESA3 versions 5.0.x to the latest version FESA3 7.0.0 perform the following steps in the FESA Eclipse Plug-in:

• Open the FESA class design
  • Press 'Update FESA Version'
  • Press 'Synchronize Source Code'
• Open the FESA deploy-unit
  • Press 'Update FESA Version'
  • Press 'Synchronize Source Code'
• Open the FESA instantiation document
  • Press 'Update FESA Version' if required
  • Press 'Promote Instances'

Alternatively take a look at the FESA3 command line tool and the script templates.

Eclipse-Neon incluiding FESA Eclipse Plug-In 2.9.10 supports FESA3 7.0.0 .

Detailed information

• 'Update FESA Version' will increase the FESA version number of classes and deploy-units, copy your design file to *.backup and then run a python script to automatically modify the XML design if required. Please check the Eclipse console output for details.
• Check that the FESA deploy unit reference the correct FESA class version before updating
• 'Synchronize Source Code' will update the generated C++ code and the XML design of the deploy-unit and/or instantiation file according to the changes in the current XML design.
• 'Promote Instances' will modify the FESA instantiation file if required according to the updated XML schema.

The migrator will perform all the required design changes. Reverse migration is not possible.

The new cmw-data version also requires the migrator to make changes to the c++ code. Strings were passed as "const char**", this is now "const char* const*". The migrator will convert this but may miss strange formatting or typedefs.

FEC

• Adaption of links in /common/export/nfsinit/<FEC> depending on environment, e.g.

FESA Version	Initialization Script	SAFTlib
FESA3 5.0.2	e.g. ln -s ../global/fesa_64bit_dev_environment 30_fesa or ln -s ../global/fesa_64bit_pro_environment 30_fesa	e.g. ln -s ../global/timing-rte-tg-doomsday-v4.0.5 20_timing-rte
FESA3 7.0.0	e.g. ln -s ../global/fesa_64bit_dev_environment 30_fesa or ln -s ../global/fesa_64bit_pro_environment 30_fesa	e.g. ln -s ../global/timing-rte-tg-enigma-v5.0.1-alpha 20_timing-rte

Older FESA versions

If you want to migrate from a version older than 5.0.2, please contact FESA support.

Changes from 5.0.x to 7.0.0

System core component changes

New Makefiles

FESA now uses makefiles from CERN Common Build System 2.13.3

New Middleware

cmw-rda3 V3.1.0 zeromq 4.3.1 cmw-util 4.0.0 cmw-log 3.6.0 cmw-data 3.0.0 cmw-dir 3.4.1

FESA is no longer compatible with cmw-rda2 (this should not cause any problems.)

There is currently no support for RBAC. Experimental support present in 5.0.1 was removed in this release.

cmw-data strings The type used to pass character arrays has been chan changed. String functions that used "const char**" now use "const char* const*"

e.g. const char* const* getDetailedStatus_labels(std::size_t& size) const;

clang support

The framework and Classes can be built using the clang compiler. This will not be used in production but is for compatibility with clang analysis tools.

Boost 1.69

Compatibility with Boost 1.53/54:

Previously FESA used Boost 1.54 and the system default is 1.53. These versions are compatible with each other. If FESA software mixes the FESA Boost and System Boost there may be compatibility problems that were not present when using an older FESA version.

On asl, boost 1.69 is currently only available as static libraries

Memory-mapped structures aligned corrected

* [FESA-7228] Use common meta-data library for RDA3 * [FESA-7226] Alignment of fesa-core/fesa-core-cern memory-mapped structures

* [FESA-7257] Strings definitions in header files

Timing Interface

* Timing Interface The saftlib interface has changed significantly with v2. If using only the TimingEventSource no changes are required, latency is improved and timestamps will be UTC. If using saftlib directly, there is a migration guide at https://www-acc.gsi.de/wiki/Timing/Saftlib2MigrationGuide

SCU Image Compatibility

Due to a change in the kernel, the image for the 7.0.0 environment is not compatible with that for the 5.0.2 environment. 7.0.0 uses the Enigma Timing Runtime Environment which is compatible with the 'current' SCU ramdisk image (2019-08-12) Most SCUs are configured to use the 'current' image. /common/export/nfsinit/scuxl1234 20_timing-rte -> ../global/timing-rte-tg-enigma-v5.0.1-alpha /common/tftp/csco/pxe/pxelinux.cfg scuxl1234 -> scuxl

5.0.x uses the Doomsday Timing Runtime Environment which is not compatible with the current image, it requires the previous SCU ramdisk image (2019-05-08) /common/export/nfsinit/scuxl5678 20_timing-rte -> ../global/timing-rte-tg-doomsday-v4.0.5 /common/tftp/csco/pxe/pxelinux.cfg scuxl5678 -> scuxl.doomsday

SCU Firmware Compatibility

Enigma RTE is compatible with Doomsday firmware, if new features are not used an update is not immediately required.

SCU ramdisk image 2019-08-12 for SCU3 has new kernel New kernel not compatible with Doomsday Timing Release Previous kernel not compatible with Enigma Timing Release Saftlib interface has changed significantly FESA 5.0.2 built for Doomsday FESA 7.0.0 built for Enigma

Behavioural Changes:

[FESA-7037] Option to ignore invalid persistence data at startup

The DeployUnit binary has a new commandline option "-ignorePersistenceErrors".

/startManually_Some_DU_M.sh -f -ignorePersistenceErrors

This allows a FESA class to start with a persistence file that contains invalid items without having to delete the entire file.

[FESA-6988] Check set-action RDA data container for unexpected value-items

The RDA data for a Setting may not contain unexpected value-items. In a partial setting, all value-items sent must be valid or an exception will be thrown detailing the list of expected value-items. In previous versions, unknown value-items were ignored. This feature was requested to prevent silent failures when value-item names change.

[FESA-7156] Allow user code to validate a filter before accepting a subscription

It is now possible to reject a subscription request if it includes an invalid filter. The client will see an RDA exception and the subscription will not be started.

The Action class provides the isFilterValid method:

// This method is called when a new subscription is requested. Returning false will abort the subscription.
bool GetHazelnut::isFilterValid(const fesa::AbstractDevice& abstractDevice, const HazelnutFilterData& filter) const
{
    //Device& device = static_cast<Device&>(abstractDevice);
    return true;
}

[FESA-7126] getMaxSize() not available in acquisition field with history

API inconcistency fixed.

[FESA-7265] Clean FESA shutdown and restart

FESA now captures SIGINT / Control-C and initiates a clean shutdown. All FESA-managed threads are shut down and DU main() is exited.

If your FESA software needs to release resources there are new methods in RTDeviceClass / ServerDeviceClass that are called just before the Deploy Unit is shut down.

void RTDeviceClass::specificShutDown() 
{ 
// This method is executed just before a normal shut down of the process. 
}
void ServerDeviceClass::specificShutDown() 
{ 
// This method is executed just before a normal shut down of the process. 
}

[FESA-6942] Implement "forwarding" event source

Configuration Changes

State item

The redundant "state" item has been removed from class and deploy unit (was: /*/information/state/)

Global Device Name

The Global Device Name has been changed from a random ID to a name automatically generated from class/DU/SCU:

GD_789ABC -> GD_DeploymentUnit_Class.scuname.

Cycle-bound properties and fields

Multiplexed - a field has settings for each cycle

Setting fields and Properties may be multiplexed / non-multiplexed

Cycle-bound - device stores cycle details with each acquisition

Acquisition fields and Properties may be cyclebound / non-cyclebound

A Device's Multiplexed and Cycle-bound attributes can be set separately.

If they are the same, behaviour is equivalent to previously where everything was called "Multiplexed"

Multiplexed Cycle-bound
(Current Multiplexed)
Settings per beam process
White Rabbit Cycle stamp

Multiplexed Non-cycle-bound
Settings per beam process
No Timing Cyclestamp

Non-Multiplexed Cycle-bound
One Setting for all beam processes
White Rabbit Cycle stamp

Non-Multiplexed Non-cycle-bound
(Current Non-Multiplexed)
One Setting for all beam processes
Single Acquisition History

The migrator handles all renaming in the design / instance files.

If cycle-bound is not specified in the instance file, it takes the value of 'multiplexed'

Code changes

// Device Methods
device->isCycleBound()
device->isMultiplexed()
// Property methods
fesa:Property* property = MyclassServiceLocator_->getProperty(Myclass::Property::Version);
// Property is cycle-bound or multiplexed
property->isSelectorNeeded
property->isMultiplexed (for compatibility)
// Property may be cycle-bound / multiplexed
property->isCycleBoundCapable()
property->isMultiplexedCapable
// Property is cycle-bound / multiplexed in design
property->isCycleBound()
property->isMultiplexed()
// Property is cycle-bound / multiplexed in design and device instance
property->accessPointNeedsSelector(const Device& device)

Device Property::accessPointNeedsSelector(device)
Replaces isAccessPointMultiplexed()

Only one MainMuxCriterion is allowed. It is not possible to mix e.g. Sequence multiplexed and BeamProcess cycle-bound

Cycle = Beam Proces / Sequence / Chain

Cycle Selector "FAIR.SELECTOR.P=1"

Setting Slot - Memory reserved for a setting value. Every valid cycle has a setting slot (64 for sequence multiplexed)

Acquisition Slot - index into a rolling buffer for the storage of acquisition values

Rolling Buffer - circular buffer storing cycle/timestamps/value. Old acquisition values are overwritten and lost.

[FESA-7131] Ensure validity of 2D array values in instance files

When the values for a 2D array are given in an instance file, and the maximum size of the array is not used, the rows must have the same size.

[FESA-7241] Missing scheduling-unit in DU should produce a warning

Validating the Deploy Unit will generate the warning "The Scheduling Unit X is not Referenced". The DU can be built and run without error if a missing SU is required.

[FESA-7202] Support event-queue-size of 0 in deploy-unit

An event queue of size zero is allowed. This prevents actions from accumulating if the action is slower to execute that the event generation interval. An unlimited event queue length is no longer allowed to prevent run-away memory usage. The default was previously -1 (unlimited) and changed to 1000.

[FESA-6886] Allow to use a global config field as an array dimension of normal devices

Other

shutdown on sigint would sometimes crash

2D arrays offset calculation issue

---