Add systematic tests for data validity propagation (#8369)

* spec tests: Data validity propagation
* update documentation links spec <-> tests

Co-authored-by: Dietrich Rothe <dietrich.rothe@desy.de>

CMakeLists.txt

@@ -91,6 +91,8 @@ if(TESTING_IS_ENABLED)
   FILE( COPY ${CMAKE_SOURCE_DIR}/tests/test5.map DESTINATION ${PROJECT_BINARY_DIR})
   FILE( COPY ${CMAKE_SOURCE_DIR}/tests/testDataValidity1.map DESTINATION ${PROJECT_BINARY_DIR})
   FILE( COPY ${CMAKE_SOURCE_DIR}/tests/testDataValidity2.map DESTINATION ${PROJECT_BINARY_DIR})
+  FILE( COPY ${CMAKE_SOURCE_DIR}/tests/testDataValidityPropagation.map DESTINATION ${PROJECT_BINARY_DIR})
+  FILE( COPY ${CMAKE_SOURCE_DIR}/tests/testDataValidityPropagation2.map DESTINATION ${PROJECT_BINARY_DIR})
   FILE( COPY ${CMAKE_SOURCE_DIR}/tests/test.dmap DESTINATION ${PROJECT_BINARY_DIR})
   FILE( COPY ${CMAKE_SOURCE_DIR}/tests/configReaderDevice.map DESTINATION ${PROJECT_BINARY_DIR})
   FILE( COPY ${CMAKE_SOURCE_DIR}/tests/validConfig.xml DESTINATION ${PROJECT_BINARY_DIR})

doc/spec_dataValidityPropagation.dox

@@ -13,16 +13,16 @@ namespace ChimeraTK {
 
 \anchor dataValidity_1
  
-- 1.1 In ApplicationCore each variable has a data validiy flag attached to it. DataValidity can be 'ok' or 'faulty'.
-- 1.2 This flag is automatically propagated: If any of the inputs of an ApplicationModule is faulty, the data validity of the module becomes faulty, which means
-all outputs of this module will automatically be flagged as faulty.
+- \anchor dataValidity_1_1 1.1 In ApplicationCore each variable has a data validiy flag attached to it. DataValidity can be 'ok' or 'faulty'. [No explicit test]
+- \anchor dataValidity_1_2 1.2 This flag is automatically propagated: If any of the inputs of an ApplicationModule is faulty, the data validity of the module becomes faulty, which means
+all outputs of this module will automatically be flagged as faulty. [\ref testDataValidity_2_3_3 "T"]
       Fan-outs might be special cases (see 2.4).
-- 1.3 If a device is in error state, all variables which are read from it shall be marked as 'faulty'. This flag is then propagated through all the modules (via 1.1.2) so it shows up in the control system.
-- 1.4 The user code has the possibility to query the data validity of the module
-- 1.5 The user code has the possibility to set the data validity of the module to 'faulty'. However, the user code cannot actively set the module to 'ok' if any of the module inputs are 'faulty'.
-- \anchor dataValidity_1_6 1.6 The user code can flag individual outputs as bad. However, the user code cannot actively set an output to 'ok' if the data validity of the module is 'faulty'. \ref dataValidity_comment_1_6 "(*)"
-- 1.7 The user code can get the data validity flag of individual inputs and take special actions.
-- 1.8 The data validity of receiving variables is set to 'faulty' on construction. Like this, data is marked as faulty as long as no sensible initial values have been propagated.
+- \anchor dataValidity_1_3 1.3 If a device is in error state, all variables which are read from it shall be marked as 'faulty'. This flag is then propagated through all the modules (via 1.2) so it shows up in the control system. [\ref testDataValidity_1_3 "T"]
+- \anchor dataValidity_1_4 1.4 The user code has the possibility to query the data validity of the module [No explicit test]
+- \anchor dataValidity_1_5 1.5 The user code has the possibility to set the data validity of the module to 'faulty'. However, the user code cannot actively set the module to 'ok' if any of the module inputs are 'faulty'. [No explicit test]
+- \anchor dataValidity_1_6 1.6 The user code can flag individual outputs as bad. However, the user code cannot actively set an output to 'ok' if the data validity of the module is 'faulty'. \ref dataValidity_comment_1_6 "(*)" [\ref testDataValidity_1_6 "T"]
+- \anchor dataValidity_1_7 1.7 The user code can get the data validity flag of individual inputs and take special actions. [No explicit test]
+- \anchor dataValidity_1_8 1.8 The data validity of receiving variables is set to 'faulty' on construction. Like this, data is marked as faulty as long as no sensible initial values have been propagated. [\ref testDataValidity_1_8 "T"]
 
 ### Comments
 
@@ -33,42 +33,41 @@ all outputs of this module will automatically be flagged as faulty.
 
 ### 2.1 MetaDataPropagatingRegisterDecorator (*)
 
-- 2.1.1 Each input and each output of a module (or fan out) is decorated with a MetaDataPropagatingRegisterDecorator (except for the TriggerFanOut, see. \ref dataValidity_2_4 "2.4")
-- 2.1.2 The decorator knows about the module it is connected to. It is called the 'owner'.
-
-- 2.1.3 **read:** For each read operation it checks the incoming data validity and increases/decreases the data fault counter of the owner.
-- \anchor dataValidity_2_1_5 2.1.5 **write:** When writing, the decorator is checking the validity of the owner and the individual flag of the output set by the user. Only if both are 'ok' the output validity is 'ok', otherwise the outgoing data is send as 'faulty'.
+- \anchor dataValidity_2_1_1 2.1.1 Each input and each output of a module (or fan out) is decorated with a MetaDataPropagatingRegisterDecorator (except for the TriggerFanOut, see. \ref dataValidity_2_4 "2.4") [\ref testDataValidity_2_1_1 "T"]
+- \anchor dataValidity_2_1_2 2.1.2 The decorator knows about the module it is connected to. It is called the 'owner'. [No explicit test]
+- \anchor dataValidity_2_1_3 2.1.3 **read:** For each read operation it checks the incoming data validity and increases/decreases the data fault counter of the owner. [\ref testDataValidity_2_1_3 "T"]
+- \anchor dataValidity_2_1_5 2.1.5 **write:** When writing, the decorator is checking the validity of the owner and the individual flag of the output set by the user. Only if both are 'ok' the output validity is 'ok', otherwise the outgoing data is send as 'faulty'. [\ref testDataValidity_1_6 "T"]
 
 ### 2.2 removed
 
 ### 2.3 ApplicationModule
 
--  \anchor dataValidity_2_3_1  2.3.1 Each ApplicationModule has one data fault counter variable which is increased/decreased by EntityOwner::incrementDataFaultCounter() and  EntityOwner::decrementDataFaultCounter.
-- 2.3.2 All inputs and outputs have a MetaDataPropagatingRegisterDecorator.
-- \anchor dataValidity_2_3_3 2.3.3 The main loop of the module usualy does not care about data validity. If any input is invalid, all outputs are automatically invalid \ref dataValidity_comment_2_3_3a "(*)". The loop just runs through normaly, even if an input has invalid data. \ref dataValidity_comment_2_3_3b "(*)"
-- 2.3.4 Inside the ApplicationModule main loop the module's data fault counter is accessible. The user can increment and decrement it, but has to be careful to do this in pairs. The more common use case will be to query the module's data validity.
+-  \anchor dataValidity_2_3_1  2.3.1 Each ApplicationModule has one data fault counter variable which is increased/decreased by EntityOwner::incrementDataFaultCounter() and  EntityOwner::decrementDataFaultCounter. [\ref testDataValidity_2_3_1 "T"]
+- \anchor dataValidity_2_3_2  2.3.2 All inputs and outputs have a MetaDataPropagatingRegisterDecorator. [\ref testDataValidity_2_1_1 "T"]
+- \anchor dataValidity_2_3_3 2.3.3 The main loop of the module usually does not care about data validity. If any input is invalid, all outputs are automatically invalid \ref dataValidity_comment_2_3_3a "(*)". The loop just runs through normally, even if an input has invalid data. \ref dataValidity_comment_2_3_3b "(*)" [\ref testDataValidity_2_3_3 "T"]
+- \anchor dataValidity_2_3_4 2.3.4 Inside the ApplicationModule main loop the module's data fault counter is accessible. The user can increment and decrement it, but has to be careful to do this in pairs. The more common use case will be to query the module's data validity. [\ref testDataValidity_2_3_4 "T"]
 
 ### 2.4 TriggerFanOut
 \anchor dataValidity_2_4
  
 The TriggerFanOut is special in the sense that it does not compute anything, but reads multiple independent poll-type inputs when a trigger arrives, and pushes them out. In contrast to an ApplicationModule or one of the data fan-outs, their data validities are not connected.
 
-- 2.4.1 Only the push-type trigger input of the TriggerFanOut is equiped with a MetaDataPropagatingRegisterDecorator.
-- \anchor dataValidity_2_4_2 2.4.2 The poll-type data inputs do not have a MetaDataPropagatingRegisterDecorator. \ref dataValidity_comment_2_4_2 "(*)".
+- \anchor dataValidity_2_4_1 2.4.1 Only the push-type trigger input of the TriggerFanOut is equiped with a MetaDataPropagatingRegisterDecorator. [\ref testDataValidity_2_4_1 "T"]
+- \anchor dataValidity_2_4_2 2.4.2 The poll-type data inputs do not have a MetaDataPropagatingRegisterDecorator. \ref dataValidity_comment_2_4_2 "(*)".[No explicit test]
 
-- 2.4.3 The individual poll-type inputs propagate the data validity flag only to the corresponding outputs.
-- \anchor dataValidity_2_4_4 2.4.4 Although the trigger conceptually has data type 'void', it can also be `faulty` \ref dataValidity_comment_2_4_4 "(*)". An invalid trigger is processed, but all read out data is flagged as `faulty`.
+- \anchor dataValidity_2_4_3 2.4.3 The individual poll-type inputs propagate the data validity flag only to the corresponding outputs. [\ref testDataValidity_2_4_3 "T"]
+- \anchor dataValidity_2_4_4 2.4.4 Although the trigger conceptually has data type 'void', it can also be `faulty` \ref dataValidity_comment_2_4_4 "(*)". An invalid trigger is processed, but all read out data is flagged as `faulty`. [\ref testDataValidity_2_4_1 "T"]
 
 ### 2.5 Interaction with exception handling
 
 See @ref spec_execptionHandling.
 
-- 2.5.1 The MetaDataPropagatingRegisterDecorator is always placed *around* the ExceptionHandlingDecorator if both decorators are used on a process variable. Like this a `faulty` flag raised by the ExceptionHandlingDecorator is automatically picked up by the MetaDataPropagatingRegisterDecorator.
-- 2.5.2 The first failing read returns with the old data and the 'faulty' flag. Like this the flag is propagated to the outputs. Only further reads might freeze until the device is available again.
+- \anchor dataValidity_2_5_1 2.5.1 The MetaDataPropagatingRegisterDecorator is always placed *around* the ExceptionHandlingDecorator if both decorators are used on a process variable. Like this a `faulty` flag raised by the ExceptionHandlingDecorator is automatically picked up by the MetaDataPropagatingRegisterDecorator. [\ref testDataValidity_1_3 "T"]
+- \anchor dataValidity_2_5_2 2.5.2 The first failing read returns with the old data and the 'faulty' flag. Like this the flag is propagated to the outputs. Only further reads might freeze until the device is available again. [\ref testDataValidity_1_3 "T"]
 
 ### 2.6 Application class
 
-- 2.6.1 For device variables, the requirement of setting receiving endpoints to 'faulty' on construction can not be fulfilled. In DeviceAccess the accessors are bidirectional and provide no possibility to distinguish sender and receiver. Instead, the validity is set right after construction in Application::createDeviceVariable() for receivers.  
+- \anchor dataValidity_2_6_1 2.6.1 For device variables, the requirement of setting receiving endpoints to 'faulty' on construction can not be fulfilled. In DeviceAccess the accessors are bidirectional and provide no possibility to distinguish sender and receiver. Instead, the validity is set right after construction in Application::createDeviceVariable() for receivers.  
 
 ### Comments:
 
@@ -85,7 +84,7 @@ See @ref spec_execptionHandling.
 3. Implementation details
 -------------------------
 
-- 3.1 The decorators which manipulate the data fault counter are responsible for counting up and down in pairs, such that the counter goes back to 0 if all data is ok, and never becomes negative.
+- \anchor dataValidity_3_1 3.1 The decorators which manipulate the data fault counter are responsible for counting up and down in pairs, such that the counter goes back to 0 if all data is ok, and never becomes negative. [No explicit test]
 
 4. Circular dependencies
 ------------------------
@@ -100,7 +99,7 @@ If modules have circular dependencies, the algorithm described in \ref dataValid
 - \anchor dataValidity_4_1_2 4.1.2 All modules which have a circular dependency form a _circular network_.[\ref dataValidity_test_TestCircularInputDetection "T"]
      - \anchor dataValidity_4_1_2_1 4.1.2.1 Also entangled circles of different variables which intersect in some of the modules are part of the same circular network.[\ref dataValidity_test_TestCircularInputDetection2 "T"]
      - \anchor dataValidity_4_1_2_2 4.1.2.2 There can be multiple disconnected circular networks in an application.[\ref dataValidity_test_TestCircularInputDetection2 "T"]
-- 4.1.3 Circular inputs and circular networks are identified at application start after the variable networks are established.
+- \anchor dataValidity_4_1_3 4.1.3 Circular inputs and circular networks are identified at application start after the variable networks are established.
 - \anchor dataValidity_4_1_4 4.1.4 As long as at least one _external input_ of any module in the _circular network_ is invalid, the invalidity flag is propagated as described in
  \ref dataValidity_1 "1." [\ref dataValidity_test_OneInvalidVariable "T"]
 - \anchor dataValidity_4_1_5 4.1.5 If and only if all _external inputs_ of one _circular network_ are back to DataValidity::ok, all _circular inputs_ of the _circular network_ ignore the
@@ -119,8 +118,8 @@ the data content at the _circular inputs_ is based on invalid data. If it is str
 
 - \anchor dataValidity_4_3_1 4.3.1 In addition to the owner (see \ref dataValidity_2_3_1 "2.3.1"), the _circular network_ (\ref dataValidity_4_1_2 "4.1.2") also gets an atomic invalidity counter.(\ref dataValidity_comment_4_3_1 "*").
 - \anchor dataValidity_4_3_2 4.3.2 Each module and each _circular input_ knows its _circular network_ [\ref dataValidity_test_TestCircularInputDetection2 "T"]
-- 4.3.3 If an _external input_ receives data, it increases/decreases the _circular network_'s invalidity counter, together with the owner's invaliditys counter.
-- 4.3.4 If a module estimates its validity (as used in \ref dataValidity_2_1_5 "2.1.5"), it returns
+- \anchor dataValidity_4_3_3 4.3.3 If an _external input_ receives data, it increases/decreases the _circular network_'s invalidity counter, together with the owner's invaliditys counter.
+- \anchor dataValidity_4_3_4 4.3.4 If a module estimates its validity (as used in \ref dataValidity_2_1_5 "2.1.5"), it returns
     - `DataValidity::ok` if the module's internal invalidity counter is 0 (\ref dataValidity_4_1_6 "4.1.6")
     - `DataValidity::ok` if the module's internal invalidity counter is not 0 and the _circular network_'s invalidity counter is 0 (\ref dataValidity_4_1_5 "4.1.5")
     - `DataValidity::faulty` if both counters are not 0 (\ref dataValidity_4_1_4 "4.1.4")

tests/testDataValidityPropagation.map

+# name              n_elements     address         size     bar width fracbits signed R/W
+dev.i1                0x00000001    0x00000000    0x00000004  1    32    0      1     RO
+dev.i3                0x00000001    0x00000008    0x00000004  1    32    0      1     RO
+dev.i4                0x00000001    0x00000004    0x00000004  1    32    0      1     RW

tests/testDataValidityPropagation2.map

+# name              n_elements     address         size     bar width fracbits signed R/W
+dev.i1                0x00000001    0x00000000    0x00000004  1    32    0      1     RO
+dev.i2                0x00000001    0x00000004    0x00000004  1    32    0      1     RO
+dev.i3                0x00000001    0x00000008    0x00000004  1    32    0      1     RO