The GCI Interface

This chapter contains information about the Generic Compiler Interpreter (GCI) interface and how to adapt the generated code.

The first part of this chapter describes for example the GCI interface model, the GCI interface using natural language and C and it provides details for the implementor of the interface. The different parts are explained in detail with several recommendations and examples of use.

The second part of this chapter describes how adapt the generated C code with the system that is to be tested. This includes for example descriptions of the use of a code generator, the adaption of the generated code, the running of the C Code Generator and the structure of the generated code.

Table of Contents 

• Overview of the GCI Interface
• The GCI Interface Model
• Informal Description of the Test Run Model
• Which Does What?
• Case Studies
• Methods Used
• Introduction to the GCI Interface
• GCI Interface -- C Style
• Predefined Types
• Management Interface
• Behavior Interface
• Operational Interface
• Value Interface
• Examples
• Encoding Decoding Examples
• TTCN Examples
• Adaption of the Generated Code
• The Missing Functionality
• The GCI Interface Model
• The Adaptor Functionality
• Adaptor Contents
• Extra Adaptor Functionality

Overview of 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 Adaptor) 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 Adaptor 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 264 : 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 cases to run using the supervisory functions. The test cases 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 265 : Start of test run

The test case typically at some point will try to send a message on some PCO. The TTCN Runtime Behavior then passes the information which message should be sent and on which PCO to the Test Adaptor. It is the responsibility of the Test Adaptor 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 Adaptor until it returns to the TTCN Runtime Behavior. When control does return 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 Adaptor in order to take a snapshot of the IUT. Within the snapshot, the Test Adaptor then typically checks all PCO's for incoming messages and all timers for time-outs. If a message has arrived on a PCO, the Test Adaptor must decode the message and translate it into a proper GCI value. If a timer has timed out, the Test Adaptor must record which timer. The Test Adaptor 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 266 : 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 Adaptor immediately. The Test Adaptor 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 Adaptor. It is meant to describe the model and basic assumptions being made.

TTCN Runtime Behavior	Test Adaptor
SEND: Builds the object to be sent and requests the actual sending from the Test Adaptor.	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 Adaptor, 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 267.

Figure 267 : 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 Adaptor function Send. By doing this, the TTCN Runtime Behavior has ensured that the message gets sent on whatever PCO was stated. The Test Adaptor 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 268 : 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 Adaptor 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 269, 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 269 : 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 Adaptor 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 Adaptor writer would get very little support from the compiler. From a the Test Adaptor writers point of view, he might want to address the fields using names and also get type checking aid from the compiler. The Test Adaptor 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 Adaptor 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 Adaptor 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 Adaptor 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 Adaptor 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 Adaptor.

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 Adaptor.

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 Adaptor. 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 Adaptor 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 Adaptor. 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:

• Primitives to build and access components of structured values
• Primitives to find and set the type of values
• Primitives to convert base values to and from the value domain of the target language

Value primitives can be further divided in the groups:

• SEQUENCE values, which include SET values and also TTCN ASP, PDU and Struct types
• SEQUENCE OF values, which include SET OF values
• CHOICE values
• OBJECT IDENTIFIER values
• BASE values, integers, booleans, strings and reals

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.

GCI Interface -- C Style

This section is a description of GCI. It describes what each function does and why it is used. Some of the functions must be implemented by you in your adaptor. See section Adaption of the Generated Code.

Predefined Types

This is two GCI value types with their respective value set:

GciStatus = { GciNotOk, GciOk }

GciVerdict = { GciFail, GciInConc, GciPass, GciNone}

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.

GciStatus GciInit()

Initiates the TTCN Runtime Behavior. Must be called before any test cases are started.

GciVerdict GciStartTestCase( const char* testCaseName )

Shall run a test case or all test cases in a test case group.

GciVerdict GciStartTestComponent(const char* testCompName)

Shall run a test case or all test cases in a test case group.

GciTCList GciGetTestCaseList()

Will return a list of test case or test case group names. If the function fails for some reason NULL shall be returned.

GciTCList GciGetTestCaseGroupList()

Will return a list of test case group names. If the function fails for some reason NULL shall be returned.

GciValue* GciGetValue( const char* name )

Will return the value named by name. If name is invalid NULL is returned.

int GciGetNoOfTimers( )

Will return the number of timers in the system.

int GciGetNoOfPCOs( )

Will return the number of PCOs in the system.

char* GciGetTimerName( int timer )

Will return the name of the given timer.

char* GciGetPCOName( int pco )

Will return the name of the given PCO.

int GciGetNoOfComponents( GciConf conf )

Will return the number of components in the given configuration.

GciComponent* GciGetComponent( GciConf conf, int index )

Will return the indexed component in the given configuration.

char* GciGetComponentName( GciComponent* conp )

Will return the name of the given component.

int GciGetComponentType( GciComponent* conp )

Will return the type of the given component (GciMTC or GciPTC).

int GciGetComponentDescriptor( GciComponent* conp )

Will return the descriptor of the given component.

char** GciGetComponentCPs( GciComponent* conp )

Will return the CPs used by the given component.

char** GciGetComponentPCOs( GciComponent* conp )

Will return the PCOs used by the given component.

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.

GciStatus GciTimeout( int timerd )

Used to tell the TTCN Runtime Behavior that the timer identified by timerd has timed out.

GciStatus GciReceive( int pcod, GciValue* msg )

Used to tell the TTCN Runtime Behavior that a message has been received.

GciStatus GciDone( int ptc )

Used to tell the TTCN Runtime Behavior that a PTC has terminated its execution.

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.

GciValue* GciReadTSPar(const char* name, const char* pRef)

Shall return the value of the test suite parameter identified with name and/or PIXS/PIXIT reference pRef. If for any reason this could not be done, NULL should be returned.

GciStatus GciConfig( GciConf )

Shall implement the given configuration (concurrent TTCN).

GciStatus GciCreate(int ptc, char* tree, GciValue* args)

This functions is called when a PTC is to be created to run a given dynamic behavior with the given arguments (concurrent TTCN).

GciValue* <TS_Op>( <Arguments> )

Every test suite operation must have this function defined. The name shall be the same as in the ATS and arguments must match the parameters in the ATS.

GciStatus GciSnapshot()

Shall read the status of the IUT. Must do two things: a) Any messages received must be delivered to the TTCN Runtime Behavior using GciReceive and b) the TTCN Runtime Behavior must be told of any timers that have timed out using GciTimeout. Snapshot shall return GciOk or GciNotOk.

GciStatus GciSend( int pcod, GciValue* obj )

Shall send the message on the PCO. Note that the message is given in the GCI value representation and therefore probably needs some form of encoding before actually being sent.

GciStatus GciImplicitSend( GciValue* value )

This function is called by the run-time behavior when an Implicit Send Event occurs in the test suite. It is up to the adaptor writer to define its exact implementation.

GciStatus GciStartTimer( int timerd, long timerDuration,
int timerUnit)

Shall start the timer with the given duration. Note that timer duration value is optional in TTCN but is always present here.

GciStatus GciCancelTimer( int timerd )

Shall stop the timer. Note that timerd is optional in TTCN but always present here.

long GciReadTimer( int timerd )

Shall return the current timer value. Note that the actual assignment of the timer value to a DataObjectReference in TTCN shall be handled by the TTCN Runtime Behavior.

GciStatus GciLog( int logId, const char* logString)

Shall put the log message on the log. The logId is an added classification of the logString. The TTCN Runtime Behavior will use this function at all relevant places.

logId	Description	The logString must contain:
Msg	General message
StartTC	Start test case	The name of the test case
StopTC	Stop test case	The name of the test case
StartTS	Start test step	The test step name
StopTS	Stop test step	The test step name
StartDEF	Start default	The default name
StopDEF	Stop default	The default name
Verdict	Final verdict set	The verdict set
PVerdict	Prel. verdict set	The verdict set
Match	Line tried matches	Line number
NoMatch	Line tried does not match	Line number
SendE	Send Event	The PCO name The type of message sent Constraint name
RecE	Receive Event1	The PCO name The type of message received Constraint name
OtherE	Otherwise Event	The PCO name
TimeoutE	Timeout Event	The timer name
Assign	Assignment	The Left hand side The right hand side (textually)
StartT	Start timer	The timer name The timer duration
StopT	Stop timer	The timer name
CancelT	Cancel timer	The timer name
ReadT	Read timer	The timer name The timer value
Attach	Attachment	The name of the attached test step
ImplSend	Implicit send	The PCO name The message type
Goto	Goto	The line number to which the jump will be made
Rec	Receive2	The PCO descriptor number
Timeout	Timeout3	The timer descriptor number

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.

Base Types/Values

These functions are used to transform actual values into the GCI representation. The interface is on base types only, so TTCN simple types are not visible in the interface.

GciValue* GciMkINTEGER( int num )
int GciGetINTEGER( GciValue* value )

Used for integer values, and simple type values with base type integer.

GciValue* GciMkBOOLEAN( int bool )
int GciGetBOOLEAN( GciValue* value)

Used for Boolean values, and simple type values with base type Boolean.

GciValue* GciMkREAL(int mantissa, int base, int exponent)
GciReal GciGetREAL( GciValue* value)

Used for Real values, and simple type values with base type Real.

GciValue* GciMkBIT_STRING( const char* str )
char* GciGetBIT_STRING( GciValue* value)

Used for bit string values, and simple type values with base type bit string.

GciValue* GciMkHEXSTRING( const char* str )
char* GciGetHEXSTRING( GciValue* value)

Used for hex string values, and simple type values with base type hex string.

GciValue* GciMkOCTET_STRING( const char* str )
char* GciGetOCTET_STRING( GciValue* value)

Used for octet string values, and simple type values with base type octet string.

GciValue* GciMkNumericString( const char* str )
char* GciGetNumericString( GciValue* value)

Used for values numerical strings, and simple type values with base type numerical string.

GciValue* GciMkPrintableString( const char* str )
char* GciGetPrintableString( GciValue* value)

Used for Printable string values, and simple type values with base type Printable string.

GciValue* GciMkTeletexString( const char* str )
char* GciGetTeletexString( GciValue* value)

Used for Teletex string values, and simple type values with base type Teletex string.

GciValue* GciMkVideotexString( const char* str )
char* GciGetVideotexString( GciValue* value)

Used for Videotex string values, and simple type values with base type Videotex string.

GciValue* GciMkVisibleString( const char* str )
char* GciGetVisibleString( GciValue* value)

Used for Visible string values, and simple type values with base type Visible string.

GciValue* GciMkIA5String( const char* str )
char* GciGetIA5String( GciValue* value)

Used for IA5string values, and simple type values with base type IA5string.

GciValue* GciMkT61String( const char* str )
char* GciGetT61String( GciValue* value)

Used for T61string values, and simple type values with base type T61string.

GciValue* GciMkISO646String( const char* str )
char* GciGetISO646String( GciValue* value)

Used for ISO646string values, and simple type values with base type ISO646string.

GciValue* GciMkGraphicalString( const char* str )
char* GciGetGraphicalString( GciValue* value)

Used for Graphical string values, and simple type values with base type Graphical string.

GciValue* GciMkGeneralString( const char* str )
char* GciGetGeneralString( GciValue* value)

Used for General string values, and simple type values with base type General string.

GciValue* GciMkENUMERATED( int value )
int GciGetENUMERATED( GciValue* value)

Used for Enumerated values, and simple type values with base type Enumerated.

GciValue* GciMkCHOICE(const char* name, GciValue* value)
GciValue* GciGetCHOICE( GciValue* value)
char* GciGetCHOICEName( GciValue* value)

Used for Choice values, and simple type values with base type Choice.

GciValue* GciMkOBJECT_IDENTIFIER()
int GciOBJECT_IDENTIFIERSize( GciValue* value)
GciValue* GciAddOBJECT_IDENTIFIERComponent(
GciValue* value, int comp)
int GciGetOBJECT_IDENTIFIERComponent( GciValue* value,
int index)

Used for Object identifier values, and simple type values with base type Object identifier.

GciValue* GciMkObjectDescriptor( const char* str )
char* GciGetObjectDescriptor( GciValue* value)

Used for ObjectDescriptor values, and simple type values with base type ObjectDescriptor.

GciValue* GciMkNULL( )
int GciGetNULL( GciValue* value)

Used for Null type values, and simple type values with base type Null type.

GciValue* GciMkANY( GciValue* value )
GciValue* GciGetANY( GciValue* value)

Used for ANY values, and simple type values with base type ANY.

GciValue* GciMkR_TYPE( int value )
int GciGetR_TYPE( GciValue* value)

Used for R_Type values, and simple type values with base type R_Type.

GciValue* GciMkPDU( GciValue* value )
GciValue* GciGetPDU( GciValue* value)

Used for PDU values, and simple type values with base type PDU.

Base Functions Valid for All Values (Hard and Soft)

int GciGetType( GciValue* val )

Shall return the type of a value. The type is represented as the number used to identify global objects, see Identifying Global Objects in TTCN/ASN.1. The function is valid for all values, but some values may be untyped in which case the function returns 0.

GciValue* GciSetType( int type, GciValue* val )

Shall set the type of a value. Uses the same number as above. Valid for all values. Returns the input value with type set.

Soft Value Management

The functions are divided into two meta sets derived from ASN.1: The sequence, and the sequence of, corresponding to struct and array in C. The choice type of ASN.1 is not represented as a meta class because all values in the GCI value representation can be typed and therefore is the choice value implicit in GCI.

The functions only works within their intended set (e.g. GciSetField(GciMkSEQUENCE(2), 1, GciMkINTEGER()) is well defined but GciSetField(GciMkSEQUENCEOF(), 0, GciMkINTEGER()) is not defined and certainly is unpredictable.

Sequence and Set Types/Values

GciValue* GciMkSEQUENCE( int size )

Creates a sequence value with size children.

GciValue* GciSetField( GciValue* seq, int index,
GciValue* fld )

Sets the field identified by index to the given value. Indices start at 0. The function is undefined for indices greater than the size of the sequence.

GciValue* GciGetField( GciValue* seq, int index )

Returns the field identified by index. Indices start at 0. The function is undefined for indices greater than the size of the sequence.

int GciSeqSize( GciValue* seq )

Returns the number of fields declared in the sequence seq.

Sequence of and Set of Types/Values

GciValue* GciMkSEQUENCEOF()

Creates a sequence of value.

GciValue* GciAddElem( GciValue* seqOf, GciValue* elem )

Adds the element elem to the end of sequence of seqOf.

GciValue* GciGetElem( GciValue* seqOf, int index )

Returns the element number index of the sequence of seqOf. Indices start at 0. The function is undefined for indices greater than current size.

int GciSeqOfSize( GciValue* seqOf )

Returns the current number of elements in seqOf.

Hard Value Management

These functions work correctly for values of correct type, and returns NULL or 0 if a value of the wrong type is used. <type> and <field> are the names found on types and fields (parameters etc.) found in the ATS.

GciValue* GciMk_<type>()

This function allocates a new value of the type <type>

GciValue* GciGet_<type>_<field>( GciValue* seq )

This function is used for sequences, sets, choices and TTCN types other than simple types. Shall return the value of the field named <field> in the type <type> or NULL if the type of the value does not match <type>.

GciStatus GciSet_<type>_<field>( GciValue* seq,
GciValue* fld )

This function is used for sequences, sets, choices and TTCN types other than simple types. Shall set the specified field <field> in type <type>. If the type of the value does not match <type> then the function is a no operation.

GciStatus GciAdd_<type>_Elem(GciValue* seq, GciValue* elem)

This function is used for sequence of and set of ASN.1 types. It adds one more element to the sequence (or set) of elements.

GciValue* GciGet_<type>_Elem( GciValue* seq, int ix,
GciValue* elem )

This function is used for sequence of and set of ASN.1 types. It returns the element indexed by ix in the sequence (or set) of value.

int GciSize_<type>( GciValue* seq)

This function is used for sequence of and set of ASN.1 types, it returns the number of elements of such a value.

Examples

This section contains examples of how the mapping between TTCN/ASN.1 and their GCI representation could be done. The examples use a conceptual model for encoding/decoding, no error handling is done and no attention is paid to the fact that some functions would use pointers because of allocation issues.

Global objects (PCOs and types) are identified with an unique number. This number is given a symbolic reference which is its TTCN name with a D for Descriptor appended to the end of it. The number for the PCO L is therefore referenced as LD.

Encoding Decoding Examples

Each example consists of a table and the corresponding encode (and/or decode) functions. The examples focus on the value representation so the transfer syntax is simple: Each value is preceded by a header. The header contains the type of the value (as a number) and in some cases its length (element count, not size in bytes), in real ASN.1, the header would be built using tags. The header is written/read using primitives BufWriteType, BufWriteSeqOfSize, etc. They are not encode/decode primitives but rather buffer primitives.

An encode function is a function that translates the GCI value onto a buffer, and a decode function is one that reads a value from a buffer and builds a value in the GCI representation. Encoding functions are called from SEND and decoding functions are called from SNAPSHOT. The buffer has type Buffer and could be anything behaving as a sequence of bytes. The primitives BufReadInt, BufReadBool are used to read and write GCI basic values.

ASN.1 SEQUENCE Type

Figure 270 : Example

Encode Using Soft Model

void EncodeT1( Buffer buf, GciValue* v)
{
  BufWriteType( buf, T1d );
  BufWriteInt( buf, GciGetField( v, 1 ));
  BufWriteBool( buf, GciGetField( v, 2 ));
}

Encode Using Hard Model

void EncodeT1( Buffer buf, GciValue* v )
{
  BufWriteType( buf, T1d );
  BufWriteInt( buf, GciT1_a( v ));
  BufWriteBool( buf, GciT1_b( v ));
}

Decode Using Soft Model

void DecodeT1( Buffer buf, GciValue* v)
{
  int i;

  v = GciMkSEQUENCE( 2 );
  if ( BufReadType( buf ) != T1d )
    Error();
  GciSetType( T1d, v );

  i = BufReadInt( buf );
  GciSetField( v, GciMkINTEGER( i ), 1 );

  i = BufReadBool( buf );
  GciSetField( v, GciMkBool( i ), 2 );
}

ASN.1 SEQUENCE OF Type

Figure 271 : Example

Encode Using Soft Model

void EncodeT2( Buffer buf, GciValue* v )
{
  int i;

  BufWriteType( buf, T2d );
  BufWriteSeqOfSize( buf, GciSize( v ) );
  for (i = 1 ; i <= GciSize( v ) ; i++ )
    {
      EncodeT1( buf, GciGetElem( v, i ) );
    }
}

Decode Using Soft Model

void DecodeT2( Buffer buf, GciValue* v )
{
  int i, seqOfSize;
  GciValue* elem;

  if ( BufReadType( buf ) != T2d )
    Error();

  GciSetType( T2d, v );

  seqOfSize = BufReadSeqOfSize( buf );
  for ( i = 1 ; i <= seqOfSize ; i++ )
    {
      DecodeT1( buf, elem );
      GciAddElem( v, elem );
    }
}

ASN.1 CHOICE

Figure 272 : Example

Encode Using soft Model

void EncodeT3( Buffer buf, GciValue* v )
{
  switch ( GciGetType( v ))
    {
    case T1d:
      EncodeT1( buf, v );
      break;
    case T2d:
      EncodeT2( buf, v );
      break;
    default:
      Error();
    }
}

Decode Using Soft Model

void DecodeT3( Buffer buf, GciValue* v )
{
  switch ( BufGetType( v ))
    {
    case T1d:
      DecodeT1( buf, v );
      break;
    case T2d:
      DecodeT2( buf, v );
      break;
    default:
      Error();
    }
}

In-Line ASN.1 Type

Figure 273 : Example

Encode Using Soft Model

void EncodeT4( Buffer buf, GciValue* v )
{
  GciValue* tmp;

  BufWriteType( T4d );
  /* Encode first field */
  EncodeT1( GciGetField( v, 1 ));
  /* Now encode inline type definition */
  tmp = GciGetField( v, 2 );
  BufWriteInt( buf, GciGetField( tmp, 0 ));
  EncodeT2( buf, GciGetField( tmp, 1 ));
}

Decode Using Soft Model

void DecodeT4( Buffer buf, GciValue* v)
{
  int i;
  GciValue* tmp;

  v = GciMkSEQUENCE( 2 );
  if ( BufReadType( buf ) != T4d )
    Error();
  GciSetType( T4d, v );
  DecodeT1( buf, tmp );
  GciSetField( v, 1, tmp );
  tmpseq = GciMkSEQUENCE( 2 );
  i = BufReadInt( buf );
  GciSetField( tmpseq, 1, GciMkINTEGER( i ) );
  DecodeT2( buf, tmp );
  GciSetField( tmpseq, 2, tmp );
}

TTCN Examples

myQueue below is the Test Adaptor writers own representation of the PCO queue(s). In this example there is only one PCO, called L (Ld for its number). Note that the number Ld can be any number (most certainly not zero).

Snapshot Example

Snapshot must read the status of the IUT and tell this to the TTCN Runtime Behavior.

void GciSnapshot()
{
  GciValue* v;

  /* Check if anything has arrived,  */
  /* This would be a while statement */
  /* in a blocking context           */
  if ( ! myQueue[ 0 ].empty )
    {
      switch ( BufPeekType( myQueue[0].buf ))
        {
        case T1d:
          DecodeT1( myQueue[0].buf, v );
          break;
        case T2d:
          DecodeT2( myQueue[0].buf, v );
          break;
        default:
          Error();
        }

      GciReceive( Ld, v );
    }

  /* Nothing has happened. */
}

Send Example

For the send example the following ASP table is used to show an API view of encode.

Figure 274 : Example

/* Two examples of send functionality */
GciStatus GciSend( int pcoDescr, GciValue* msg )
{
  if ( pcoDescr == PcoToSocket )
    {
      /* Encode first */
      if ( GciGetType( msg ) == T1d )
        {
          EncodeT1( buf, msg );
          BufSocketSend( buf );
        }
    }
  else if ( pcoDescr == PcoToAPI )
    {
      if ( GciGetType( msg ) == TCONreqd )
        {
          Buffer pdu;
          EncodeT1( pdu, GciGetField( msg, 1 ));
          /* Call to lower layer */
          T_CONreq( GciGetField( msg, 0 ), pdu );
       }
    }
}

Adaption of the Generated Code

After the TTCN code has been translated, there are a couple of things that has to be done in order adapt the generated code to the system it intends to test. This section describes how such an adaptation should be performed.

The Missing Functionality

Figure 275 displays in a very simple way the anatomy of an executable test suite.

Figure 275  : The anatomy of an executable test suite

When code is generated by the code generator, it does not know anything about the system it is about to test. In any way, it assumes it will have access to special functions which will be implemented by the user to support the testing of the given system.

The test support functions module is responsible for providing functionality as:

• Encoding
• Decoding
• Implementation and handling of timers
• Representation and handling of PCOs [and CPs]
• Communication with test equipment [and PTCs]
• Etc.

The Test Support Functions

The test support functions are the functions that the user must write to adapt the TTCN runtime behavior to his/her test equipment. Typically, among these functions are functions which must supply services for communication between the TTCN runtime behavior and the IUT.

We must be able to send encoded messages which the test system can understand, and also decode received messages into a representation which the TTCN runtime behavior can interpret. Timers and PCOs must be implemented, as well as other help functions which might be needed for a successful adaptation. Figure 276 shows the test support functions module in more detail.

Figure 276  : A better picture of the test support functions module

The GCI Interface Model

The TTCN runtime behavior must clearly be separated from protocol and test specific code. To succeed in doing this, we use the GCI interface model. In this section we will only shortly introduce this model, for further details, see Overview of the GCI Interface.

The GCI interface is a standardized set of functions. Communication shall only be done by calling functions, passing arguments to functions, returning values from the functions, and in no other way.

The interface is bidirectional in the meaning that both the TTCN runtime behavior and the test adaptor (which is part of the test support functions module) must provide services to each other. The TTCN runtime behavior shall at least provide services for handling values and managing tests and the test adaptor shall provide the protocol/test equipment specific parts of an executable.

With this information in mind, it is time to update Figure 276, into Figure 277 which introduces the GCI interface model to the system.

Figure 277  : Introducing the GCI interface model

As can be seen in Figure 277 the GCI interface is divided into a management and an operational interface. These two interfaces will be described in more detail in The Adaptor Functionality.

The Adaptor Functionality

In this section we will concentrate on the functionality of the adaptor. We will do so by looking at the GCI interfaces; the GCI management, behavior and operational interface. Observe by looking at Figure 277 that the only values passing these interfaces must be values as defined by Overview of the GCI Interface. The GCI interface also allows the user to use a soft or a hard representation of these values. For more details in the subject, see Value Representation and Value Interface.

The GCI management interface describes the management functionality (functions) that the user may use in the adaptor. These functions are already implemented and may be used freely in the adaptor files.

GCI Management Interface

The GCI management functionality consists of functions for initializing and managing test runs. These functions provide an API to the TTCN runtime behavior.

GciStatus GciInit()

This function must be the first function to be called. It initializes the TTCN runtime behavior module.

GciVerdict GciStartTestCase(char* TestCaseOrTestGroup)

Calling this function with a test case name will start and run the given test case. The verdict returned is the verdict set by the test case.

If the function is called with a test group name, it will start and run the given test group. The verdict returned is the product of the verdicts set in the test cases or test groups contained in the given test group. The individual verdicts from the different test cases or test groups has to be extracted from the log. The verdict algorithm for test groups is defined as follows:

1. the verdict is PASS iff the verdict of every test case PASS
2. the verdict is INCONC iff the verdict of at least one test case is INCONC and all others are PASS
3. the verdict is FAIL iff the verdict of at least one test case is FAIL

If the given name is not a valid test case nor a test group, the function will return GciNotOk and log the following message:



No such Test Case or Test Group as <name> to run!

GciVerdict GciStartTestComponent( char* StepName,
GciValue* args )

This function works just like GciStartTestCase but is used to start a parallel test component when using concurrent TTCN.

GciTCList* GciGetTestCaseList()

This function returns a list of all test case names (including test cases in test groups). List of character strings.

GciTCList* GciGetTestGroupList()

This function returns a list of all test group names (including test groups in test groups). List of character strings.

GciValue* GciGetValue(char* TTCNObjectName)

This function returns the TTCN object as a GciValue*. If the object name is not a TTCN name (name defined within the test suite) the function will return NULL and log the following message:



GciGetValue: Could not find <name>! NULL returned

If the object name is a TTCN name, but not an object (variable, constant, etc...) the function will return NULL and log the following message:



GciGetValue: <name> not an instance! NULL returned

int GciGetNoOfTimers( )

This function returns an integer which is the amount of timers in the system.

int GciGetNoOfPCOs( )

This function returns an integer which is the amount of PCOs in the system.

char* GciGetTimerName( timer )

This function returns the name of a given timer.

char* GciGetPCOName( pco )

This function returns the name of a given PCO.

int GciGetPCOType( pco )

This function returns the type of a given PCO.

int GciGetNoOfComponents( GciConf conf )

This function returns the amount of components in a given component configuration.

GciComponent* GciGetComponent( GciConf conf, int index )

This function returns the indexed component in a given configuration.

char* GciGetComponentName( GciComponent* comp )

This function returns the name of a given component.

int GciGetComponentDescriptor( GciComponent* comp )

This function returns the descriptor of a given component.

int GciGetComponentType( GciComponent* comp )

This function returns the type (MTC or PTC) of a given component.

char** GciGetComponentCPs( GciComponent* comp )

This function returns the CPs used by the given component.

char** GciGetComponentPCOs( GciComponent* comp )

This function returns the PCOs used by the given component.

GCI Behavior Interface

The GCI behavior functionality consists of functions that have to be called within the GciSnapshot function (described in GCI operational interface). These functions are to be used when the user wishes to report a change of the IUT status to the TTCN runtime behavior.

GciStatus GciReceive( int pcod, GciValue* value )

This function will insert the received object into the internal PCO queue indexed by the PCO descriptor pcod.

GciStatus GciTimeout( int timerd )

This function will change the status of the internal timer indexed by the timer descriptor timerd. The timer will be marked as timed out.

GciStatus GciDone( int ptc )

This function will mark the given PTC as done with its execution.

Adaptor Contents

It is up to the user to implement the functions in the GCI operational interface. These functions are called from the TTCN runtime behavior and should not be removed even if they are empty.

The function bodies and declarations are found in the template adaptor files, but the function bodies are empty. They only contain a print statement about the function not being implemented.

In the ITEX installation directory, there is a subdirectory containing different adaptor templates. The adaptor template called simple is the default one which is copied to the code directory if the user has no adaptor at all. A different adaptor template, called timers adaptor, contains a simple implementation of timers. Finally, an adaptor template called general adaptor, contains an adaptor example with a general encoder and decoder. Useful hints might be found by looking at these small code segments.

GCI Operational Interface

The GCI operational interface is the part of the ETS which is dependent on the protocol/test equipment. The process of adaptation is simply to implement these functions so that the TTCN runtime behavior can communicate with the system it intends to test.

GciValue* GciReadTSPar( char* name, char* pRef )

The user has to implement how to read the test suite parameters. This code will be called one time for each test suite parameter in the system. Here name is the name of the test suite parameter and pRef is the PICS/PIXIT field (ex. file). The value returned by this function must be a pointer to a valid GciValue structure which can be successfully used by the TTCN runtime behavior.

GciStatus GciConfig( GciConf conf )

When using concurrent TTCN the user is responsible for creating the configurations to be used for a given test. The creation of those configurations is done in this function using a set of help functions in the management interface to traverse the information.

GciStatus GciSnapshot()

A very important functionality which the user has to implement is the snapshot functionality. Two important things must be done here:

• Communication lines (PCOs) must be checked. If something has been received, we must decode the message, build a receive object and insert the object into the correct, internal PCO queue by using the GciReceive function with appropriate PCO descriptor. To build the desired object the user can choose to either use the soft or the hard GCI value interface. If the hard interface is used, the Generate GCI Hard Values toggle button must be set when running the CCG to force it to generate this type of value interface.
• Time must be checked and the status of timers must be updated. If the user uses the simple adaptor template he/she must self keep track of time and use GciTimeout to mark a timer as timed out. If the user uses the timers adaptor template he/she can use the AdSetTime function (see below) to have this work done automatically.

GciStatus GciSend(int pcod, GciValue* value)

The user is responsible for implementing the send functionality. This involves identifying a given PCO and doing some kind of encoding before sending away the message.

GciStatus GciStartTimer(int timerd, long duration,
int unit)

Timers must also be implemented by the user if he/she uses the simple adaptor. To start a timer the TTCN runtime behavior will call this function. If the user uses the timers adaptor, this function is already implemented.

GciStatus GciCancelTimer(int timerd)

If the system can start a timer, it must also be able to stop it. This function is called to achieve that result. It is up to the user to implement this functionality if he/she uses the simple adaptor. If the user uses the timers adaptor, this function is already implemented.

long GciReadTimer(int timerd)

Starting and stopping timers is of course important, but reading a timer value must also be allowed. This function is called when a timer is read. It is up to the user to implement this functionality if he/she uses the simple adaptor. If the user uses the timers adaptor, this function is already implemented.

GciStatus GciLog(int logId, char* LogString)

The user has to implement parts of the logging facility. As the GCI document describes, some log identifiers are already implemented. The log identifiers (identifies the type of log message) in this function should NOT be changed as they follow the values listed in the GCI document. On the other hand, the user is free to decide where to log his/her messages (file, shell, etc...).

Auxiliary Adaptor Functionality

This section describes some extra functionality which is included in the adaptor.

FILE* logStream;

This is the stream to where log messages are written. The default value is stdout and is set in the main function, but can be set to whatever stream the user wishes to use.

CCGPRINT(string, file, string2)

This is a macro (#define) for:



fprintf(stderr, "%s%s%s", string, file, string2)

and may be changed or deleted by the user. This is the macro that prints the messages:



Function <name> in file: adaptor.c is not written!

for all functions not implemented by the user.

enum IcObjectEnum

Enumerated type over all the tables (constraints, test cases, test steps, etc...) and types in the test suite.

extern const int Gc<tablename>D = {int}

Constant numbers for all tables (test case table, PCO table, timer table, etc...) in TTCN. Used to search in the IcSymTab array (see symbol table below). An example is for GcTestCaseD = 517.

extern IcSymTabEntry IcSymTab[]

Global symbol table (array) with all the objects in the test system. The interesting fields in an array item are:



char* Name;
int Type;
GciValue** Val;

The Name is the name of the object, the Type field is Gc<tablename>D and Val is a pointer to the value, if it is a variable.

extern int IcSymTabLen;

Integer telling the size of the internal symbol table (see below).

extern int IcSymTabOffset;

Offset which must be subtracted from an object descriptor to be able to index correctly into the internal symbol table.

Simple Adaptor Functionality

The simple adaptor template includes all empty functions for the previously described GCI operational functions.

Timer Adaptor Functionality

The timers adaptor template is the simple adaptor template with timers implemented. The timer functionality is described below.

The implemented timer structure looks as follows:

typedef struct AdTimeStruct 
{
  int    Id;
  int    Status;
  long   Duration;
  long   StartTime;
  int    Unit;
  struct AdTimeStruct* Next;
} AdTimeStruct;

The fields are described below:

Id	Timer descriptor to uniquely identify the timer
Status	ADRUNNING or ADNOTRUNNING
Duration	Timer duration
StartTime	Start time for the timer
Unit	Unit (min, sec, msec, usec, or psec)
Next*	Pointer to next timer or NULL (linked list)

The status field above can take the values defined below:

#define ADRUNNING    0
#define ADNOTRUNNING  1

These values are the different status values that the implemented timers may have. If a timer has started the timer will have the status ADRUNNING, otherwise it will have ADNOTRUNNING.

AdTimeStruct* AdTimers;

Global list of timers.

long AdGlobalTime = 0;

Global variable keeping time.

Bool AdSetTime(long)

This function sets the time by the algorithm

AdGlobalTime = argument

long AdNow()

This function returns the value kept in the AdGlobalTime variable.

Bool AdInitTimers()

This function initializes and creates the linked list of all the timers in the test suite.

The time in the Adaptor is a long int and should be measured as milli seconds.

Extra Adaptor Functionality

Encoding and Decoding

A test suite has no knowledge of the encoding and decoding rules of the actual application protocol. The definition of signal components and description of the signal flows is done in an abstract and high-level manner. The physical representation of the signal components and the definition of the actual transfer syntax is not defined within the test suite.

The encoding and decoding rules (functions) simply define a common transfer syntax between the test equipment and the executable test suite.

It is up to the user to write his/her own encoding and decoding rules using the GCI value representation. Even if the CCG comes with an adaptor template that includes a general encoder and decoder, these rules can not be used at all times.

For test applications that need to send the same type of messages back and forth through a communication channel, the encoding and decoding functions must be related to each other in such way that the decoding function is the inverse function of the encoding function. This gives the following simple rule:

Message = Decode( Encode ( Message ) )

This simply states, that if you decode an encoded message, you will get the original message back.

For applications that send and receive messages of different types (for example an application sending commands to an interface one way and receiving command results the other way), the encoding and decoding rules might not be related at all.

It is up to the user to identify how he/she needs to encode and decode messages to successfully be able to communicate with his/her test equipment.

Communication

From an abstract point of view, sending and receiving is done over PCOs (Points of Control and Observation). The physical representation of these PCOs has to be defined by the user. It can be shared memory, serial communication, UNIX sockets, etc. This, of course, is only done on the controlling side. The PCOs have to be connected somewhere to the test equipment and the responsibility for this is put upon the user.

The Test Environment

In some cases it is important to have a good knowledge about the test equipment/environment.

If the executable test suite is to run within the test equipment, i.e. the communication between the ETS and the IUT is done within the test equipment, the ETS has to be moved (cross compiling or if possible compiling within the test equipment).

Timers might also need some attention. As timers are implemented differently on different systems the implementation of the timers might differ.

Semantics of Functions

Timers

Timers are simply a number of constructions to keep track of each of the test suite timers. In the generated code a timer is represented by an integer descriptor which uniquely identifies it. One way to implement the timeout functionality is to maintain an ordered list of the running timers. In this case it is easy to see how long we must wait until the next timeout is scheduled.

PCOs

PCOs are constructions to handle the PCO queues. Each PCO should have buffers for sending and receiving, a method for retrieving the status of the receive buffer and additional information such as channels and ports must be provided for the physical channels.