LibItsSremSsem_Functions.ttcn

/**
 *    @author   ETSI / STF517
 *    @version  $URL$
 *              $Id$
 *    @desc     Module containing common functions for ITS SREMM SSEM
 *    @copyright   ETSI Copyright Notification
 *                 No part may be reproduced except as authorized by written permission.
 *                 The copyright and the foregoing restriction extend to reproduction in all media.
 *                 All rights reserved.
 *
 */
module LibItsSremSsem_Functions {
    
    // LibCommon
    import from LibCommon_Sync all;
    import from LibCommon_Time all;
    import from LibCommon_VerdictControl all;
    
    // LibIts
    import from ITS_Container language "ASN.1:1997" all;
    import from DSRC language "ASN.1:1997" all;
    
    // LibItsCommon
    import from LibItsCommon_TypesAndValues all;
    import from LibItsCommon_Templates all;
    import from LibItsCommon_Functions all;
    import from LibItsCommon_Pixits all;
    
    // LibItsSremSsem
    import from LibItsSremSsem_TestSystem all;
    import from LibItsSremSsem_TypesAndValues all;
    import from LibItsSremSsem_Templates all;
    import from LibItsSremSsem_Pics all;
    import from LibItsSremSsem_Pixits all;

    group utFuntions { 
            
        /**
         * @desc    Requests to bring the IUT in an initial state
         * @param   p_init The initialisation to trigger.
         */
        function f_utInitializeIut(template (value) UtSremInitialize p_init) runs on ItsSremSsem {
            
            utPort.send(p_init);
            tc_wait.start;
            alt {
              [] utPort.receive(UtSremResults: { utSremInitializeResult := true }) {
                    tc_wait.stop;
                    log("*** " & testcasename() & ": INFO: IUT initialized ***");
                }
                [] tc_wait.timeout {
                    log("*** " & testcasename() & ": INFO: Could not receive expected UT message from IUT in time ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
                [else] { // Shortcut defaults
                    //f_sleep(0.050); // 50 ms
                    repeat; 
                }
            }            
        }
        
        /**
         * @desc    Triggers an event from the application layer
         * @param   p_event The event to trigger.
         */
        function f_utTriggerEvent(
                                  in template (value) UtSremTrigger p_event
        ) runs on ItsSremSsem {
            
            utPort.send ( p_event );
            tc_wait.start;
            alt {
              [] utPort.receive ( UtSremResults: { utSremTriggerResult := true }) {
                tc_wait.stop;
              }
              [] utPort.receive ( UtSremResults: { utSremTriggerResult := false }) {
                    tc_wait.stop;
                    f_selfOrClientSyncAndVerdict("SREM Trigger failed", e_error);
                }
                [] tc_wait.timeout {
                    log("*** " & testcasename() & ": INFO: Could not receive expected UT message from IUT in time ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
                [else] { // Shortcut defaults
                    //f_sleep(0.050); // 50 ms
                    repeat; 
                }
            }
            
            return;
        }
        
        /**
         * @desc    Updates an event from the application layer
         * @param   p_event The event to trigger.
         */
        function f_utUpdateEvent(
                                 in template (value) UtSremUpdate p_event
        ) runs on ItsSremSsem {
            
            utPort.send ( p_event );
            tc_wait.start;
            alt {
              [] utPort.receive ( UtSremResults: { utSremUpdateResult := true }) {
                    tc_wait.stop;
                }
              [] utPort.receive ( UtSremResults: { utSremUpdateResult := false }) {
                    tc_wait.stop;
                    f_selfOrClientSyncAndVerdict("SREM Update failed", e_error);
                }
                [] tc_wait.timeout {
                    log("*** " & testcasename() & ": INFO: Could not receive expected UT message from IUT in time ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
                [else] { // Shortcut defaults
                    //f_sleep(0.050); // 50 ms
                    repeat; 
                }
            }
            
            return;
        }
        
    } // End of group utFuntions
    
    group adapterControl {
        
        /**
         * @desc Initialise secure mode if required
         */
        function f_initialiseSecuredMode(
                                         in charstring p_certificate_id := PX_CERT_FOR_TS 
        ) runs on ItsSremSsem {
            
            if (PICS_IS_IUT_SECURED == true) {
                
                if(e_success != f_acTriggerSecEvent(m_acEnableSecurity(p_certificate_id))) { 
                    log("*** INFO: TEST CASE NOW STOPPING ITSELF! ***");
                    stop;
                }
            }
            
        } // End of function f_initialiseSecuredMode()
        
        function f_uninitialiseSecuredMode() runs on ItsSremSsem {
            
            if (PICS_IS_IUT_SECURED == true) {
                f_acTriggerSecEvent(m_acDisableSecurity);
            }
            
        } // End of function f_initialiseSecuredMode()
        
        /**
         * @desc    Triggers event in the test system adaptation.
         * @param   p_event The event to trigger
         * @return  FncRetCode
         */
        function f_acTriggerSecEvent(template (value) AcSecPrimitive p_event) runs on ItsSremSsem return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            acPort.send(p_event);
            tc_ac.start;
            alt {
                [] acPort.receive(m_acSecResponseSuccess) {
                    tc_ac.stop;
                }
                [] acPort.receive {
                    tc_ac.stop;
                    log("*** " & __SCOPE__ & ": ERROR: Received unexpected message ***");
                    f_selfOrClientSyncAndVerdict("error", e_error);
                }
                [] tc_ac.timeout {
                    log("*** " & __SCOPE__ & ": ERROR: Timeout while waiting for adapter control event result ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
            }
            
            return v_ret;
        }
        
    } // End of group adapterControl 
    
    group altsteps {
        
        /**
         * @desc Default handling cf01 de-initialisation.
         */
        altstep a_cf01Down() runs on ItsSremSsem {
            [] a_shutdown() {
                f_poDefault();
                f_cfDown();
                log("*** a_cf01Down: INFO: TEST COMPONENT NOW STOPPING ITSELF! ***");
                stop;
            }
        }
        
        /**
         * @desc The base default.
         */
        altstep a_default() runs on ItsSremSsem {
            [] sremSsemPort.receive(mw_sremInd(mw_sremPdu(mw_defaultSrem))) { 
                log("*** " & testcasename() & ": INFO: SREMM received in default ***");
                vc_sremReceived := true;
                repeat;
            }
            [] sremSsemPort.receive(mw_ssemInd(mw_ssemPdu(mw_defaultSsem))) { 
                log("*** " & testcasename() & ": INFO: SREMM received in default ***");
                vc_ssemReceived := true;
                repeat;
            }
            [] sremSsemPort.receive {
                log("*** " & testcasename() & ": ERROR: Received an unexpected message ***");
                f_selfOrClientSyncAndVerdict("error", e_error);
            }
            [] any timer.timeout {
                log("*** " & testcasename() & ": INCONC: Timeout while awaiting the reception of a message ***");
                f_selfOrClientSyncAndVerdict("error", e_timeout);
            }
            [] a_shutdown() {
                f_poDefault();
                f_cfDown();
                log("*** " & testcasename() & ": INFO: TEST COMPONENT NOW STOPPING ITSELF! ***");
                stop;   
            }
        }
        
        /**
         * @desc The default for handling upper tester messages.
         */
        altstep a_utDefault() runs on ItsSremSsem {
            var UtSremEventInd v_sremevent;
            var UtSsemEventInd v_ssemevent;
            [] utPort.receive(UtSremEventInd:?) -> value v_sremevent {
                //store every upper tester indication received
                vc_utSremEvents[lengthof(vc_utSremEvents)] := v_sremevent;
                repeat;
            }
            [] utPort.receive(UtSsemEventInd:?) -> value v_ssemevent {
                //store every upper tester indication received
                vc_utSsemEvents[lengthof(vc_utSsemEvents)] := v_ssemevent;
                repeat;
            }
            [] utPort.receive {
                log("*** " & testcasename() & ": INFO: Received unhandled/unknown UT message from IUT ***");
                repeat;
            }
        }
        
    } // End of group altsteps

    group mapSpatConfigurationFunctions {
        
        /**
         * @desc    Setups default configuration   
         * @param   p_certificate_id The certificate identifier the TA shall use in case of secured IUT
         */
        function f_cfUp(
                        in charstring p_certificate_id := PX_CERT_FOR_TS
        )  runs on ItsSremSsem /* TITAN TODO: system ItsSremSsemSystem */ {
            
            map(self:acPort, system:acPort);
            map(self:utPort, system:utPort);
            map(self:sremSsemPort, system:sremSsemPort);
            
            // Connect
            f_connect4SelfOrClientSync();
            activate(a_cf01Down());
            
            // Initialise secured mode
            f_initialiseSecuredMode(p_certificate_id); 
            
            //Initialze the IUT
            f_prInitialState();
            
        } // End of f_cfUp
        
        /**
         * @desc    Deletes default configuration 
         */
        function f_cfDown() runs on ItsSremSsem /* TITAN TODO: system ItsSremSsemSystem */ {
            
            // Initialise secured mode
            f_uninitialiseSecuredMode();
            
            unmap(self:utPort, system:utPort);
            unmap(self:acPort, system:acPort);
            unmap(self:sremSsemPort, system:sremSsemPort);
            
            f_disconnect4SelfOrClientSync();
        } // End of f_cfDown
        
    } // End of of mapSpatConfigurationFunctions
    
    group preambles {
        
        /**
         * @desc The default preamble.
         */
        function f_prDefault() runs on ItsSremSsem {
            vc_default := activate(a_default());
            activate(a_utDefault());
        }
        
        /**
         * @desc Brings the IUT into an initial state.
         * @return FncRetCode 
         */
        function f_prInitialState() runs on ItsSremSsem return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            f_utInitializeIut(m_sremSsemInitialize);
            f_prDefault();
            return v_ret;
        }
        
    } // End of group preambles

    group postambles {
        
        /**
         * @desc The default postamble.
         */
        function f_poDefault() runs on ItsSremSsem {
            //empty
        }
        
    } // End of group postambles
    
    group sendFunctions {
        
        /**
         * @desc Sends a IVI message
         * @param p_sendMsg The IVI message to send.
         * @param p_overrideSeqNo Overrides the sequence number with the stored one. 
         */
        function f_sendSseMessage(
                                  in template (value) SignalRequestMessage p_signalRequestMessage
        ) runs on ItsSremSsem {
            sremSsemPort.send( 
                m_ssemReq(
                    m_ssemPdu(
                        m_ssem(
                            valueof(p_signalRequestMessage)
            ))));
        }
        
    } // End of group sendFunctions
    
    group receiveFunctions {
        
        /**
         * @desc Awaits a SREM and returns it
         * @param p_rcvMsg The expected message to be received.
         * @param p_rcvdMsg The received message - OUT.
         */
        function f_awaitSreMessage(
                                   in template (present) SremInd p_rcvMsg, 
                                   out SremInd p_rcvdMsg
        ) runs on ItsSremSsem {
            
            tc_ac.start;
            alt {
                [] sremSsemPort.receive(p_rcvMsg) -> value p_rcvdMsg {
                    tc_ac.stop;
                }
                [] tc_ac.timeout {
                    log("*** " & testcasename() & ": INFO: Timeout while awaiting the reception of a message ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
            }
        }
        
    } // End of group receiveFunctions
    
    group miscellaneousFunctions {
        
        /**
         * @desc Increases the RequestID number and handles the special case where the 
         *       SremIdentification number reaches the limit of 32768 and will be reset to 0.
         * @param p_requestID The RequestID number to increase.
         * @return The increased RequestID number.
         */
        function f_increaseRequestID(
                                     in RequestID p_requestID
        ) return RequestID {
            // if maximum number of 256 reached, reset it to 0
            return ((p_requestID + 1) mod 256);
        }
        
    } // End of group miscellaneousFunctions
    
} // End of module LibItsSremSsem_Functions