LibItsDenm_Functions.ttcn

/**
 *	@author 	ETSI / STF405
 *  @version 	$URL$
 *				$Id$
 *	@desc		Module containing functions for DENM
 *
 */
module LibItsDenm_Functions {
    
    // LibCommon
    import from LibCommon_Sync all;
    import from LibCommon_VerdictControl all;
    import from LibCommon_Time {
        modulepar PX_TNOAC;
        function f_sleep
    };
        
    // LibIts
    import from LibItsCommon_Functions all;
    import from LibItsDenm_TestSystem all;
    import from LibItsDenm_TypesAndValues all; 
    import from LibItsDenm_Templates all; 
    import from LibItsDenm_Pics all; 
    import from CAM_PDU_Descriptions language "ASN.1:1997" all;
    import from DENM_PDU_Descriptions language "ASN.1:1997" 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) UtInitialize p_init) runs on ItsDenm {
            
            utPort.send(p_init);
            tc_wait.start;
            alt {
                [] utPort.receive(UtResult:true) {
                    tc_wait.stop;
                    log("*** f_utInitializeIut: INFO: IUT initialized ***");
                }
                [] utPort.receive {
                    tc_wait.stop;
                    log("*** f_utInitializeIut: INFO: IUT could not be initialized ***");
                    f_selfOrClientSyncAndVerdict("error", e_error);
                }
                [] tc_wait.timeout {
                    log("*** f_utInitializeIut: INFO: IUT could not be initialized in time ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
                [else] { // Shortcut defaults
                    repeat; 
                }
            }
            
        }
        
        /**
         * @desc    Triggers event from the application layer
         * @param   p_event The event to trigger.
         */
        function f_utTriggerEvent(template (value) UtEvent p_event) runs on ItsDenm {
            var template (value) UtTrigger v_utMsg := { p_event };
            
            utPort.send(v_utMsg);
            alt {
                [] utPort.receive(UtResult:true) {
                    tc_wait.stop;
                }
                [] utPort.receive {
                    tc_wait.stop;
                }
                [] tc_wait.timeout {
                }
                [else] { // Shortcut defaults
                    repeat; 
                }
            }
        }
        
        /**
         * @desc Checks that the event was indicated at the application layer
         * @param p_event The event to check.
         * @param   p_discard The event should not appear. Default value: FALSE.
         */
        function f_utCheckEvent(template (value) UtEvent p_event, boolean p_discard) runs on ItsDenm {
            var template (value) UtCheck v_utMsg := { p_event };
            
            utPort.send(v_utMsg);
            tc_wait.start;
            alt {
                [] utPort.receive(UtResult:true) {
                    tc_wait.stop;
                    if (p_discard == false) {
                        log("*** f_utCheckEvent: INFO: Event correctly indicated at application layer ***");
                    }
                    else {
                        log("*** f_utCheckEvent: ERROR: Event indicated at application layer where it should be discarded ***");
                        f_selfOrClientSyncAndVerdict("error", e_error);
                    }
                }
                [] utPort.receive(UtResult:false) {
                    tc_wait.stop;
                    if (p_discard == false) {
                        log("*** f_utCheckEvent: ERROR: Event not correctly indicated at application layer ***");
                        f_selfOrClientSyncAndVerdict("error", e_error);
                    }
                    else {
                        log("*** f_utCheckEvent: INFO: Event not indicated at application layer***");
                    }
                }
                [] tc_wait.timeout {
                    log("*** f_utCheckEvent: ERROR: Timeout while waiting for event check result ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);                    
                }
                [else] { // Shortcut defaults
                    repeat; 
                }
            }
        }
                    
    } // End of group utFunctions

    group denmConfigurationFunctions {
        
        /**
         * @desc    Setups default configuration   
         */
        function f_cfUp() runs on ItsDenm {
            
            map(self:utPort, system:utPort);
            map(self:denmPort, system:denmPort);
            f_connect4SelfOrClientSync();
            
        } // end f_cfUp
        
        /**
         * @desc    Deletes default configuration 
         */
        function f_cfDown() runs on ItsDenm {
            
            unmap(self:utPort, system:utPort);
            unmap(self:denmPort, system:denmPort);
            f_disconnect4SelfOrClientSync();
            
        } // end f_cfDown
        
    } //end denmConfigurationFunctions
    
    group altsteps {
        
        /**
         * @desc The base default.
         */
        altstep a_default() runs on ItsDenm {
        	[] denmPort.receive(mw_denmInd(mw_denmPdu(mw_anyDenm))) { 
                log("*** a_default: INFO: DENM message received in default ***");
                vc_denmReceived := true;
                repeat;
            }
            [] denmPort.receive {
                log("*** a_default: ERROR: Received an unexpected message ***");
                f_selfOrClientSyncAndVerdict("error", e_error);
            }
            [] tc_wait.timeout {
                log("*** a_default: INCONC: Timeout while awaiting reaction of the IUT prior to Upper Tester action ***");
                f_selfOrClientSyncAndVerdict("error", e_timeout);
            }
            [] tc_ac.timeout {
                log("*** a_default: INCONC: Timeout while awaiting the reception of a message ***");
                f_selfOrClientSyncAndVerdict("error", e_timeout);
            }
            [] a_shutdown() {
                f_poDefault();
                f_cfDown();
                log("*** a_default: INFO: TEST COMPONENT NOW STOPPING ITSELF! ***");
                stop;   
            }
        }
        
        /**
         * @desc Default handling the cancellation of an event.
         * @param p_trigger Indicates if the cancellation have to be raised by the test system(e_ets) 
         *                  or at the application layer of the IUT(e_iut).
         * @param p_event The event to cancel.
         * @param p_actionId The action ID of the event to be cancelled
         */
        altstep a_cancelEvent(in template (value) Trigger p_trigger, in template (value) Situation p_event, in template (omit) ActionID p_actionId) 
        runs on ItsDenm {
            [] a_shutdown() {
                f_poCancelEvent(p_trigger, p_event, p_actionId);
                f_cfDown();
                log("*** a_cancelEvent: INFO: TEST COMPONENT NOW STOPPING ITSELF! ***");
                stop;   
            }
        }
        
    } // end group altsteps
    
    group preambles {
        
        /**
         * @desc The default preamble.
         */
        function f_prDefault() runs on ItsDenm {
            vc_default := activate(a_default());
        }
        
        /**
         * @desc Brings the IUT into an initial state.
         * @return FncRetCode 
         */
        function f_prInitialState() runs on ItsDenm return FncRetCode {
            var FncRetCode v_ret := e_success;
            
            f_utInitializeIut(m_denmInitialize);

			f_prDefault();
            
            return v_ret;
        }
        
    } // end group preambles
    
    group postambles {
        
        /**
         * @desc The default postamble.
         */
        function f_poDefault() runs on ItsDenm {
            var FncRetCode v_ret := e_success;
            //empty
        }
        
        /**
         * @desc Postamble including cancellation of an event.
         * @param p_trigger Indicates if the cancellation have to be raised by the test system(e_ets) 
         *                  or at the application layer of the IUT(e_iut).
         * @param p_event The event to cancel.
         * @param p_actionId The action ID of the event to be cancelled
         */
        function f_poCancelEvent(template (value) Trigger p_trigger, template (value) Situation p_event, template (omit) ActionID p_actionId) 
        runs on ItsDenm {
            var FncRetCode v_ret := e_success;
            
            if (valueof(p_trigger) == e_ets) {
                f_sendDenMessage(
                    m_denmReq(
                    	m_denmPdu(
                          f_getCurrentTime(),
                        	m_denmWithCause(c_dataVersionCancellation, p_event, m_eventPosition(f_getTsCurrentPosition()), f_getTsStationId())
                        )
                    )
                );
                f_sleep(PX_TNOAC);
            }
            else {
            	f_utTriggerEvent(m_utUpdateEventExpirationTime(p_event, p_actionId, 1));
                f_utTriggerEvent(m_utEventCancellation(p_event, p_actionId));
            }
            
            f_poDefault();
        }
        
    } // end group postambles
    
    group sendFunctions {
        
        /**
         * @desc Sends a DEN message
         * @param p_sendMsg The DEN message to send.
         */
        function f_sendDenMessage(template (value) DenmReq p_sendMsg) runs on ItsDenm {
            p_sendMsg.msgOut.denm.management.actionID.sequenceNo := vc_sequenceNo;
            
            denmPort.send(p_sendMsg);
        }
        
    } // end sendFunctions
    
    group receiveFunctions {
        
        /**
         * @desc Awaits a DEN message and returns it
         * @param p_rcvMsg The expected message to be received.
         * @param p_rcvdMsg The received message - OUT.
         */
        function f_awaitDenMessage(in template (present) DenmInd p_rcvMsg, out DenmInd p_rcvdMsg) runs on ItsDenm {
            
            tc_ac.start;
            alt {
                [] denmPort.receive(p_rcvMsg) -> value p_rcvdMsg {
                    tc_ac.stop;
                }
                [] tc_ac.timeout {
                    log("*** f_awaitDenMessage: INFO: Timeout while awaiting the reception of a message ***");
                    f_selfOrClientSyncAndVerdict("error", e_timeout);
                }
            }
            
        }
        
    } // end receiveFunctions
    
    group getFunctions {
        
        group iutGetFunctions {
            
            /**
             * @desc Gets IUT's default event duration
             * @return Default expiry time of DENM events
             */
            function f_getIutDefaultEventDuration() return TimeStamp {
                return PICS_DEFAULT_EXPIRY_TIME;
            }            
            
        } // end iutGetFunctions

    } // end group getFunctions
    
    group miscFunctions {
    	
    	/**
    	 * @desc       Gets a random severity
    	 * @return     Random Severity 
    	 */
    	function f_randomSeverity() return Severity {
    	   	var integer v_rnd := f_random(1, 4);
    	   	select(v_rnd) {
    	   	   case(1) {
    	   	       return informative;
    	   	   } 
               case(2) {
                   return obstacles;
               }
               case(3) {
                   return danger;
               } 
               case(4) {
                   return highestDanger;
               }
    	   	   case else {
    	   	   	   return highestDanger;
    	   	   }    	
    	   	}    	   	
    	}
    } // end miscFunctions
    
} // end LibItsDenm_Functions