IBM
Contents Index Previous Next



The GCI Interface


The Generic Compiler Interpreter (GCI) interface standardizes the communication between a TTCN component supplied by a vendor and other test system components supplied by the customer, together forming a MOT, Method Of Test.

The GCI interface focuses on what an ATS needs in order to execute in term of functionality, and on what is needed in order to integrate TTCN into a larger system. This chapter contains a natural language description of the interface and a GCI C Reference.

The GCI Interface Model

The main purpose of the GCI interface is to separate TTCN behavior from protocol and test equipment specific code. The GCI interface shall be a standardized set of functions. Communication shall be done by calling functions, passing arguments to the functions and return values from the functions, and in no other way. The interface is bidirectional which means that both parties (the TTCN Runtime Behavior and the Test Adaptation) must provide services to each other. The TTCN Runtime Behavior shall at least provide services for handling values and managing tests (evaluating test cases etc.) and the Test Adaptation shall provide the protocol/test equipment specific parts of an executable (send, snapshot, timer functions etc.). The implementation of the functions in the TTCN Runtime Behavior may only depend on the ATS and 9646-3, no extra information shall be needed to implement them.

Figure 267 : The GCI model

Informal Description of the Test Run Model

This section contains an informal description of how a test run might look like using the GCI interface. A test run is defined as a complete test session, where a selection of test cases are run to ensure a specific behavior of the IUT.

A test run begins when the user decides to run a test case or a collection of test cases. He will then use the Supervisory functions to start test cases and monitor their verdicts. The TTCN Runtime Behavior then executes TTCN, occasionally using the operational interface (send, snapshot, etc.) to gather information or to request some service. The TTCN Runtime Behavior handles verdicts internally during a test case and returns the verdict at the end of a test case.

Before using the TTCN Runtime Behavior, it must be initialized. After that the user chooses which test case to run using the supervisory functions. The test case returns a verdict which the user can use to form reports or stop test runs. The TTCN Runtime Behavior or the GCI interface does not impose any restrictions on this part. Any number of test cases can be run and each is commanded using the Supervisory functions.

Figure 268 : Start of test run

The test case at some point will try to send a message on some PCO. The TTCN Runtime Behavior then passes information to the Test Adaptation about the message to send and on which PCO to send it on. It is the responsibility of the Test Adaptation to properly encode the message and actually send it on some media (e.g. sockets, screen, printer port, pipe). Note that control is in the Test Adaptation until it returns to the TTCN Runtime Behavior. When control returns to the TTCN Runtime Behavior it assumes that the message was sent correctly and continues execution of the test case.

Eventually the test case will have emptied its possibilities to act and needs input from the environment. It therefore passes control to the Test Adaptation in order to take a snapshot of the IUT. Within the snapshot, the Test Adaptation then checks all PCO's for incoming messages and all timers for time-outs. If a message has arrived on a PCO, the Test Adaptation must decode the message and translate it into a proper GCI value. If a timer has timed out, the Test Adaptation must record which timer. The Test Adaptation acts as a filter between the IUT and the TTCN Runtime Behavior. Note that the actual reception of a message or timeout could be handled somewhere else (e.g. in an interrupt routine), only the official communication that the event has taken place must be done in SNAPSHOT.

Figure 269 : Send and Snapshot

Preliminary verdicts may be set during the test execution and when a final verdict is set, the test case returns to the Test Adaptation immediately. The Test Adaptation then has freedom to decide to continue the test run or not. A final verdict has meaning only in the context of the current test purpose. The meaning of a final verdict is not specified in the context of an entire collection of test cases. For example, when doing regression tests, all test cases should be run regardless of how many failed in order to get a complete picture of the status of the IUT.

Which Does What?

The table below summarizes the responsibilities of the two GCI parties, the TTCN Runtime Behavior and the Test Adaptation. It is meant to describe the model and basic assumptions being made.

TTCN Runtime Behavior Test Adaptation

SEND:

Builds the object to be sent and requests the actual sending from the Test Adaptation.

SEND:

Receives the object that shall be sent and transfers this to the IUT. This might include encoding in some form.

RECEIVE:

When a value is put on a PCO queue by the Test Adaptation, it remains there until a matching receive line is found in TTCN.

RECEIVE:

Builds the received object (from the IUT) into a GCI value, which may include some form of decoding, and notifies the TTCN Runtime Behavior that the message has arrived.

Sets the verdict (based on the test case).

Treats the verdict (i.e. decides if the test run should continue or not).

Impl. of value representation.

Encoders/decoders.

Uses the value repr.

Uses the value repr.

Provides test cases. The test cases are sensitive to test case selection references.

Determines which test cases to run and in which order.

Uses send on messages.

Provides the send functionality.

Uses SNAPSHOT to fix a view of the status of the IUT. Expects all changes in system status to be recorded in SNAPSHOT.

Reads system status in SNAPSHOT and records this through GCI interface for the TTCN Runtime Behavior.

Uses the LOG function to log TTCN Runtime Behavior.

Provides the LOG functionality, and also decides on what level logging should be done.

Case Studies

This section contains case studies of a send and a receive. For the case studies, we use an example PDU shown in Figure 270.

Figure 270 : Example table

Case Study: SEND

Nr Lbl Statement Line Cref Comment




L ! CR

CR_c



The semantic of the TTCN send statement is as follows:

  1. Build the SendObject using the constraint reference.
  2. Execute the assignments.
  3. Send the SendObject on the PCO.
  4. Execute the timer operations.
  5. LOG, at least the PCO and the SendObject must be logged.

The SendObject above is a temporary object containing the object to be sent. All steps above are initiated by the TTCN Runtime Behavior. Steps 3 to 5 require communication with the environment (IUT). The TTCN Runtime Behavior will build a SendObject using the constraint CR_c above. Then it will call the Test Adaptation function Send. By doing this, the TTCN Runtime Behavior has ensured that the message gets sent on whatever PCO was stated. The Test Adaptation function Send then encodes the message using the transfer syntax of the protocol and then sends the message on the medium that represents the PCO. The arguments passed to Send is the PCO and the message in the GCI representation, and the side effect of Send is to send the message in protocol representation on the PCO in test system representation. Note that the encoding and sending on a PCO might very well be represented as a function call.

Figure 271 : The send event

Case Study: RECEIVE

Nr Lbl Statement Line Cref Comment




L ? CC

CC_c



The receive is a little more complicated than the send. Send is initiated by the TTCN Runtime Behavior while receive is an internal event in the TTCN Runtime Behavior. The actual reception of messages is done in the Test Adaptation and these actions are communicated to the TTCN Runtime Behavior in SNAPSHOT. Note that there may be a difference between the reception of a message and the notification to the TTCN Runtime Behavior that the message has arrived. The TTCN Runtime Behavior calls the function SNAPSHOT and when it returns, the TTCN Runtime Behavior expects all time-outs to have been recorded and all received messages to be put on the correct PCO queues in the correct format. In this case we study the message event only and not the timeout.

A message has been received from the IUT (not necessarily in SNAPSHOT) and the TTCN Runtime Behavior must be told that the message has been received. This shall be done in SNAPSHOT using the GCI function provided. The message and the PCO must be presented in a representation understood by the TTCN Runtime Behavior. Note that the message probably needs to be translated into the GCI value representation somewhere but again not necessarily in SNAPSHOT.

If SNAPSHOT does what is stated above, the TTCN Runtime Behavior will do the following on the receive line in the test case:

The PCO queue is checked and if there is a message there, that message is matched against the constraint reference. If the message matches, it is removed from the PCO queue and the receive statement is considered to be TRUE, otherwise, the next alternative is checked.

In Figure 272, we assume that decoding is done in SNAPSHOT. The message is decoded using the value manipulating primitives of the GCI interface. When the message has been decoded into something known to the TTCN Runtime Behavior, it is easy to assign it to a PCO using the GCI function receive.

Figure 272 : The receive event

Methods Used

This section contains general thoughts on methods used for designing the GCI interface. Choices have been made such as to provide reasonable trade-offs between speed and ease of use. An efficient implementation in C should be possible with the choices made.

Identifying Global Objects in TTCN/ASN.1

One problem is how to identify global objects in TTCN, PCOs, CPs, ASPs etc. There are a number of requirements that should be met:

  1. Execution time:
    The TTCN behavior, operational and value interface functions are likely to be called many times in a time sensitive context which requires them to be fast. The management functions does not have this requirement.
  2. Compilation time:
    The Test Adaptation and the TTCN Runtime Behavior are likely to be used together with a graphical interface (GUI) or integrated into a larger system. This integration should be possible without re-compiling the GUI or the larger system every time a change has been made in the ATS. This requires that dependencies between the ATS and the management interface implementation must be kept to a minimum.

There are at least three alternative solutions to be considered:

  1. Straight name reference using target language semantics, i.e start test case "TC1" by writing the function call "TC1()" in C, and the value of the variable "TCVAR1" is expressed simply as TCVAR1
  2. Assign an integer to each object. Symbolic names could then be used. The examples from above would then be:
    #define TC1 192
    
    #define TCVAR1 1211
    
    Verdict = GciStartTestCase( TC1 );
    
    Display( GciGetValue( TCVAR1 ));
    
  3. Use string references.
    Verdict = GciStartTestCase( TC1 );
    
    Display( GciGetValue( TCVAR1 ));
    
    
    

Solution 1 gives the fastest execution but is very unsuitable for integration into a larger application. Solution 2 is at least possible to integrate into a GUI, and almost as fast as solution 1. Solution 3 is excellent for integration but gives slow execution.

In the GCI interface, we choose to use solution 3 (string references) in the management functions and solution 2 in the TTCN behavior functions. It would then be very easy to integrate an ETS into an already existing test system since the interface is string based while we still maintain speed in the execution of test cases.

A similar problem is how to identify fields in structured types. The simplest solution is to address them using integers field 0, field 1, etc., but then the Test Adaptation writer would get very little support from the compiler. From the Test Adaptation writers point of view, he might want to address the fields using names and also get type checking aid from the compiler. The Test Adaptation writer also wants to write generic functions for encode/decode. The GCI interface supports both views, one view where substructures are identified by numbers, and one which in effect use name addressing.

Test Suite Operation Definitions

The TTCN Runtime Behavior requires that all test suite operations are defined as functions at run-time. Arguments to and return values from the test suite operation functions shall use the GciValue* format. The name of the test suite operation function shall be the same as the name of the test suite operation in TTCN.

Logging

The log will provide a view of a test run. Most things happening in the system will need to be logged. We have identified a number of requirements on the log functionality:

  1. It should be possible to only log every event visible to the TTCN Runtime Behavior. I.e. the sending of a message should leave a note in the log while the internal behavior of the TTCN Runtime Behavior should not.
  2. For debug purposes, it must be possible to report every event in the system.
  3. The granularity of the log must be easy to change by the Test Adaptation writer. It should be possible to be quite specific when logging, i.e. log only sends and receives.

The method that the GCI interface suggests is massive logging. Everything is logged at any time and every type of event (send, receive etc.) is assigned a number. That way it is easy for the Test Adaptation writer to write a log function that only logs interesting log messages.

Value Representation

The GCI interface must provide a stable way of manipulating values. This is most important for the Test Adaptation writer to be able to access and build values in his encode and decode functions. The GCI interface proposes not to specify the value representation but rather the methods which can be used on it. The GCI interface specifies what the Test Adaptation writer is able to do with values. The reason for this is that most vendors supporting the GCI interface would like to have their own value representation within their TTCN Runtime Behavior, and the representation used within TTCN has different requirements than the representation needed for the Test Adaptation.

Introduction to the GCI Interface

This section contains the description of the GCI interface in natural language. The interface functionality is sorted by responsibility. The management, behavior and value interfaces are interfaces to the TTCN Runtime Behavior. The operational interface is the interface to the Test Adaptation.

Management Interface

The management interface consists of those functions necessary for initiating and managing test runs. They provide an API to the ATS. These functions are used by the Supervisory functions to govern test runs.

Initiation of the TTCN Runtime Behavior

Must be called before the TTCN Runtime Behavior is used in any way. It will read test suite variables (using primitives in the operational i/f), set up test case selection references, test suite constants and any other initialization necessary. It should only be called once.

Start Test Case

Shall run a test case according to the dynamic behavior in 9646-3. Input shall be a test case name or test case group name. The test case or all the test cases in the test group shall then be run in the order which they were listed in the ATS. If the selection reference of a test case or test case group is false, that test case or test case group shall not be executed. Verdict shall be set and communicated back to the caller. In case several test cases have been run, the verdict shall be the most negative of the verdicts from each test case (if one test case is FAIL, the verdict would be FAIL, if all are PASS, the verdict would be PASS).

Start Test Component

This function works just line the function to start test cases, but starts test components for example when concurrent TTCN is used.

Test Case List

A list of names of test cases.

Test Case Group List

A list of names of test case groups.

Number of Timers and PCOs

Two functions are needed to return information about the amount of timers and PCOs in the system.

Information About Timers and PCOs

Help functions are needed to get some extra information about timers and PCOs. (For example name and type.)

Configuration Information

A set of functions is needed to retrieve information about configurations when running concurrent TTCN.

Accessing TTCN Values

Values of TTCN (and ASN.1) objects must be accessible from the Test Adaptation. A general access function will be provided. Information passed shall be an object name and the information passed back shall be the value of the object. Valid objects shall be test suite parameters, test case selection expressions, test suite constants, test suite variables and test case variables.

Behavior Interface

The behavior interface consists of functions used to notify the TTCN Runtime Behavior of events in the IUT. The functions are a formalism of what the TTCN Runtime Behavior needs to know about the status of the IUT. The functions are implemented in the TTCN Runtime Behavior and must be used in Snapshot.

Receive

Whenever a message has been received and decoded it must be passed to the TTCN Runtime Behavior in SNAPSHOT in order for it to match it with the constraint. The information passed shall be the PCO descriptor and the value. Note that the value passed in receive must be a GciValue*.

Time Out

Whenever a timer has timed out the TTCN Runtime Behavior must be notified of it in SNAPSHOT. The information passed shall be the timer descriptor.

Done

Whenever a test component has terminated its execution the TTCN Runtime Behavior needs to know about this. The information passed is the descriptor for the given test component.

Operational Interface

The operational interface consists of those primitives necessary for the TTCN Runtime Behavior to implement TTCN, i.e. Send, Snapshot, StartTimer etc. This part of GCI can be compared to POSIX. TTCN Runtime Behavior requires that the functions are defined.

Test Suite Parameters

The TTCN Runtime Behavior shall call the Test Adaptation once for each test suite parameter during the initialization of the TTCN Runtime Behavior. Information passed shall be a handle for the value, the parameter name and the PICS/PIXIT reference.

Test Suite Operations

Each test suite operation must be defined in the Test Adaptation. The name of the test suite operation function shall be the same as in the ATS, and the order of the parameters shall also be the same.

Create

When a test component needs to be created this function will be called from the TTCN Runtime Behavior.

Configuration

When different tests are run, different configurations might be needed. This function is called from the TTCN Runtime behavior to set up a configuration before the test goes on.

Snapshot

The status of the IUT must be read. Events in the IUT must be translated for the TTCN Runtime Behavior to be aware of them. The communicating interface between the TTCN Runtime Behavior and the IUT (environment) is made up of messages that has arrived and timers that have timed out. Therefore there are only two requirements on SNAPSHOT: 1) any received messages shall be recorded and 2) any timers that have timed out shall be recorded. The recording shall be done by using the provided GCI functions described in the Behavior i/f.

Send

This function is used by the TTCN Runtime Behavior to ensure that messages get sent. Send probably involves encoding and physical sending but might as well translate to encoding of some parts of the message and use of a lower layer service. The information passed to the function shall be a PCO descriptor and the value to be sent.

Start Timer

When the TTCN Runtime Behavior needs to start a timer. Information passed shall be the timer descriptor, the integer timeout duration and the timer unit.

Read Timer

Shall pass the current timer value back to the caller. Information passed to the function shall be a timer descriptor.

Cancel Timer

Shall stop a timer identified by a timer descriptor.

Log

Shall log events on an appropriate format. An integer specifying log message type and a log string shall be passed as parameters.

Value Interface

The interface to values is a simple API in which the user is allowed to build and access GciValues in an ordered way. The actual values used are not specified, only the methods that can be used on them are included. This way will allow vendors to have their own value representation within their TTCN Runtime Behavior and still conform to GCI.

Three types of value primitives are needed. Primitives to access structured values:

Value primitives can be further divided in the groups:

Please note that SET and SET OF values are treated as SEQUENCE and SEQUENCE OF values because there is no semantic difference at this level of abstraction. The unordered behavior of SETs is considered a decoder problem and left to the decoder writer.


http://www.ibm.com/rational
Contents Index Previous Next