Technical Documentation: Internal Design of the CD-Gen

From Go4IT project

Introduction

This document describes the internal design of the CoDec Generator, whose purpose is to generate the C++ code for building a CoDec from a TTCN-3 ATS sources and C++ Codets.

Definitions

• Abstract Test Suite (ATS): test suite composed of abstract test cases (TTCN-3 source code).

• codec: encoder/decoder entity used for encoding and decoding data to be transmitted and received, respectively.

• Coding/Decoding (CoDec): entity that administers the value and type handling including encoding and decoding in the TTCN-3 test system.

• CoDec generator: the tool that produces a CoDec for a given ATS and associated Codets. Codec generator also includes a runtime library to be linked with the CoDec.

• Codet: additional logic for the TTCN-3 types, which are necessary for the CoDec generation. They are developed in C++ and provided as source code files with the corresponding ATS.

• TTCN-3 Compiler: a compiler which produces C/C++ source code for a given TTCN-3 ATS. Compiler also includes a set of runtime libraries to be linked with the compiled ATS.

• TTCN-3 Executable (TE): part of a test system that deals with interpretation or execution of a TTCN-3 ETS

• TTCN-3 Control Interfaces (TCI): three interfaces that define the interaction of the TTCN-3 Executable with the TM (TCI-TM), the CD (TCI-CD), and the CH (TCI-CH) in a test system.

• User: in this document the user is the physical person who uses the CoDec Generator as a tool to build a CoDec. He interacts directly with the generator by using its command line interface and indirectly by writing the type definitions in the TTCN-3 source files and the Codets in the C++ source files.

General Design

Figure 1: General Design

The CoDec Generator is made of two parts as shown in Figure 1:

• the CoDec generator itself, an executable tool which provides the user interface and which generates the CoDec from the TTCN-3 and C/C++ source files

• the CoDec library, which provides an implementation of the TCI and functions and mechanisms needed by the

generated CoDec.

The library shall be considered as an internal component of the CoDec generator.

Interfaces

The CoDec Generator and its library interacts with three entities

• the user, through the command line interface
• the input files (Test Suite written in TTCN-3 and C++ Codets)
• the test executable, through the TCI

User Interface

The user interface provides a command line for controlling the generation of the CoDec.

The execution is non-interactive (batch mode). The user must provide the name of TTCN-3 and C++ input files (see Section Input files).

Optional switches can be given to adjust:

• the name of the C++ output file
• options for preprocessing C++ files:

• macro definitions
• include directories

Input files

The generator uses two inputs:

• the Abstract Test Suite (TTCN-3 source files) for building the generated CoDec
• additional C++ files containing Codets for adapting the CoDec to specific characteristics of the ATS (customisation).

Abstract Test Suite

The CoDec Generator parses completely the TTCN-3 source files and extracts user types definitions, namely:

• structured types: record, set, record of, set of and union
• subtypes made from basic types

Each type definition extracted from the TTCN-3 source is mapped to a C++ class wearing the same name in the generated CoDec.

Each classes is derived from one of the C++ base classes provided by CoDec framework in the library (Section Value Framework).

Codets

Classes produced by the CoDec generator provide generic encoding and decoding functions (materialised with member functions Encode() and Decode(). Their behaviour can be customised by feeding the generator with C++ files containing Codets.

A Codet is a member function that is added to the generated class by the CoDec generator. Depending on its name, this function is called at the adequate moment while encoding or decoding the value. Possible functions are:

• PreEncode() called before encoding a value
• PreEncodeField() called before encoding a field in a structured type
• PostEncodeField() called after encoding a field in a structured type
• PostEncode() called after encoding a value
• PreDecode() called before decoding a value
• PreDecodeField() called before decoding a field in a structured type
• PostDecodeField() called after decoding a field in a structured type
• PostDecode() called after decoding a value

The content of a Codet can manipulate the value being encoded or decoded and notably make a decoding hypothesis with functions described in Section Design of the Generator.

TTCN-3 Control Interface (TCI)

The generated CoDec is compliant with the TTCN-3 Control Interface for providing the encoding/decoding service to the Test Executable.

The TCI is implemented in the CoDec Library.

Internal design of the CoDec Library

Figure 2: Internal design of the library

The CoDec Library is divided into three parts

• an implementation of the TCI that interacts with the Test Executable
• an abstraction layer, that provides a framework for representing and manipulating TTCN-3 values
• embedded mechanisms, that provides defauts codecs

The internal design of the library is shown in Figure 2.

TCI Implementation

The TCI implementation uses the C language mapping of the TCI.

It implements the "TCI-CD provided" operations (tciEncode and tciDecode) and interacts with the Test Executable using the "TCI-CD required" and the "TCI-Value" calls only.

tciEncode performs the following operations:

1. instantiate a C++ object (from the abstraction layer) corresponding to TTCN-3 value being encoded
2. retrieve the content of the value from the Test Executable using the TCI-Value interface and fill the object with it.
3. call the Encode() member function on the object
4. return the encoded message as a binary string

In case of error (unhandled exception) the function returns an empty string.

tciDecode performs the following operations:

1. instantiate a C++ object (from the abstraction layer) corresponding to decoding hypothesis (TTCN-3 type) used for decoding the value
2. call the Decode() member function on this object
3. report the content of the decoded value to the Test Executable using the TCI-Value interface

In case of error (unhandled exception) the function returns a distinct value null.

Value Framework

The abstraction layer provides a framework for representing and manipulating TTCN-3 Values. It provides four levels of abstraction. The first two layers are purely virtual classes.

• 1st layer: a root class that can represent any TTCN-3 value. It provides virtual functions for:

• querying the type of the value and the name of the module that defines this type
• querying the base TTCN-3 type (identifying the 3rd-layer class the object is derived from)
• access the parent value (when the value is contained inside a structured value)
• display the content of the value in a human readable format
• encode and decode the value

• 2nd layer: separation between primitive types (integer, bitstring, ...) and structured types (record, union, ...). The branch for primitive types provides functions for accessing and manipulating the binary content of the value (independently from its type)
• 3rd layer: classes representing TTCN-3 types (integer, bitstring, hexstring, charstring, octetstring, boolean, enum, verdict, record, record of, set, set of, union). Each class provides specialised functions for manipulating their content.
• 4th layer: classes representing TTCN-3 subtypes. These are the classes generated by the CoDec generator for representing user-defined types in the TTCN-3 sources. These classes provide functions for encoding and decoding as well as the Codets provided by the user.

Exceptions

Encoding and decoding errors are reported with exceptions.

Exceptions are represented with a class that contains:

• a reference to the value that produced the exception
• a human readable description of the error

Exceptions can be caught in PostEncode() and PostDecode() Codets. If not handled by any Codet they are ultimately caught in the TCI implementation and make tciDecode()/tciEncode() return immediately empty value/message to the Test Executable.

CoDec Framework

Each value class provides two methods Encode() and Decode() for encoding/decoding to/from a binary buffer. When working with structured types these methods are called recursively.

A binary buffer is user for storing the message being encoded or decoded. A cursor marks the current position of the codec engine in the message. It points at the next field to be encoded/decoded and is moved forwarded each time a field is processed.

Encoding

When the Encode() method is called on a value, the content of the value is encoded and written in the buffer at the position pointed by its cursor. The cursor is then moved at the end of the string written into the buffer.

In case of a structured value, Encode() is called recursively on the values contained in the fields.

Without any exterior intervention, the cursor always points at the end of the buffer, the next value to be encoded is appended at the end of the buffer.

Decoding

When the Decode() method is called on a value, the value is decoded from the content of the buffer at the current position of its cursor. The cursor is then moved at the end of the string that was decoded.

In case of a structured value, Decode() is called recursively on the values contained in the fields.

Decoding structured types is more complex. Several issue have to be addressed:

• how to decide if an optional field is present or not
• how to decide witch union variant to decode
• how to decide how many fields are present in a record of/set of
• how to split the encoded message into fields

These issues are addressed in classes generated by the CoDec generator (Section Design of the Generator).

The default behaviour is to:

• throw an exception in case of uncertainty (when reaching an optional field or a union)
• assume that all the remaining bits available in the buffer are available to decode the current value ; therefore the end of variable size values (record of, set of, bitstring, octetstring, hexstring and charstring) will match the end of the buffer
• throw an exception if there is not enough bits remaining in the buffer to decode the entire message.

Debugging Functions

The library provides debugging functions for

• tracing encode requests: the functions dump the abstract content of the value and the encoded binary message returned to the Test Executable.
• tracing decode requests: the functions dump the binary message to be decoded and the abstract value returned to the Test Executable.
• tracing calls to the TCI-Value interface

Each debugging function can be enabled or disabled. The ``enabled/disabled state is stored in a global variable and can be modified at any time.

Embedded mechanisms

The library provides default codecs for some TTCN-3 built-in types.

Primitive types are encoded as follows:

• integers use a fixed size big-endian representation, an may be signed or unsigned
• strings (bitstring, octetstring, charstring, hexstring) use binary representation of the string
• boolean: bit '1' for true and '0' for false

Internal design of the Generator

Figure 3: Internal design of the Generator

The CoDec generator is made of two layers (Figure 3): the first one for parsing the input files and the second one for generating the output files.

The parsing layer is made of two separate parsers:

• a TTCN-3 parser, which extracts the type definitions from the Abstract Test Suite
• a C++ parser, which extracts the Codet definitions from C++ source files. Before being parsed, C++ files are processed with a usual C preprocessor. The preprocessor can be configured from the command line interface (see Section User Interface).

The role of the second layer is to generate the C++ classes that represent user defined TTCN-3 types. These classes inherit from the framework described in Section Value Framework and are merged with the Codets written by the user.

Generated classes contain four groups of member functions:

1. Class manipulation functions for accessing the objects representing the fields (in structured types)
2. Codec helper functions, these function alter the decoder behaviour by making hypothesis about the binary content to be decoded:

• SetHypLength(): set the hypothetical length of an encoded variable
• SetHypFieldLength(): set the hypothetical length in bits of an individual field
• SetHypSize(): set the hypothetical length of a record of or a set of by giving the number of elements
• SetHypFieldIsPresent(): tell if an optional field is assumed to be present or not
• SetHypChosenId(): tell which field in a union is assumed to be present

1. Codets provided by the user (see Section Codets)
2. Reimplemented functions

• Encode() the encoder function, which encode the value and calls the XxxxxEncode() Codets that have been defined (eg. PreEncode())
• Decode() the encoder function, which decode the value according to the hypothesis that have been made previously and calls the XxxxxDecode() Codets that have been defined (eg. PreDecode()). If an hypothesis cannot be fulfilled, then an exception is thrown.