From OpenTTCN DocZone

Article's permanent URL

C to TTCN-3 mapping

How does it work

In the following we present an example of testing SUT written in C using UDP frame exchange between the test execution environment and the SUT. UDP frames participating in the exchange carry direct in-memory representation of C data structures and are directly usable on the SUT side using simple C-style type casts of a data pointer to a particular offset in the UDP frame.

In our example the SUT simply prints content of the C data contained in the frame it received from the test execution to the terminal window and sends the same frame back to the test execution environment. Test execution performs encoding of TTCN-3 data into C data and decoding of C data back into TTCN-3 in accordance with platform-dependent rules for C data in-memory layout specified in the C_types.ttcn TTCN-3 module. The role of this module is twofold:

• It defines mapping of C primitive types to TTCN-3.
• It defines architecture-dependent profile for C data in-memory layout as generated by C compiler using TTCN-3 'variant' attributes. For this reason, depending on the platform, C compiler flavour and compiler options, you may need to use another C_types.ttcn profile module that differs from the one above.

We mainly use this example to as an illustration demonstrating functionality of the TTCN-3 to C codec and C to TTCN-3 converter.

Generate TTCN-3 data types from C

Given C header file ApplicationTypes.h that contains original C typedefs, run this header through the C to TTCN-3 converter using the following command:

c2ttcn ApplicationTypes.h

This will generate ApplicationTypes.ttcn file containing C typedefs converted to TTCN-3 typedefs. Note that it uses definitions from C_types.ttcn.

Write and compile TTCN-3 test suite

Develop TTCN-3 test suite that uses generated TTCN-3 typedefs to represent C data.

Example frame format

For the purposes of our example we assume that UDP frames carrying C data have the following simple format:

Octet                  Frame
       +-------------------------------------+
  1    |  Type code (most significant byte)  |
       +-------------------------------------+
  2    |  Type code (least significant byte) |
       +-------------------------------------+
  3    |           Message content           |
       |              (C data)               |
  N    |                                     |
       +-------------------------------------+

First two octets of the frame tell what user-defined C data type is carried in the 'message content' part of the frame. The information about correspondence between frame type code and type of C data stored in the 'message content' part of the frame is hard-coded both in the test suite and in the SUT. Thanks to C to TTCN-3 converter used in the previous section, SUT and test execution now have a consistent view of C data contained in the remainder part of the frame ('message content' part).

Test suite example

Here you can find the test suite example: file main.ttcn.

UDP frame format is described by Message typedef in the example test suite.

You can now compile the example test suite from the command-line using the following command:

importer3 load c_test main.ttcn C_types.ttcn ApplicationTypes.ttcn

Provision TTCN-3 adapter and C SUT

You need to launch a TTCN-3 adapter containing UDP network interface code and TTCN-3 to C codec. OpenTTCN provides a generic TTCN-3 to C codec that can encode and decode arbitrary C data dynamically on the fly rather than using some hard-coded definitions. Codec can be configured with architecture-dependent C data in-memory layout profile (file C_types.ttcn).

You also need to launch a C SUT that accepts frames in the format specified above.

Run test cases, observe results

You can now run test cases. From the command-line, this can be done e.g. like this:

tester run -f -l -m -i c_test @control

Here is the resulting campaign log of the example test run: file campaign.log.

Here is the SUT window output: file sut.out

As you can see, SUT has been outputting content of C data it received from the test execution to the terminal window for debugging purposes.

Test case TC_mismatch_demo demonstrates reporting of precise location of a mismatch in C data structure. This facilitates test suite debugging and finding errors in the SUT. You receive mismatch location report of the following kind:

...
mtc : {12:47:42.596} : main.ttcn : 000974 : /* MISMATCH: incorrect content in the received value. Mismatching field: 'T.payload.struct_c.f2.u1.uf2.b3.f2.h.ah'. */ p.receive(Message :
...

Mismatching fragment diff is also highlighted in the log fragment for the received value. Both mismatch location report and mismatch diff highlighting pin-point the place where the mismatch has happened.

Type mapping

Type mapping rules for converting C data types to TTCN-3 are presented in Table 1. All types prefixed with c_ are defined in C_types.ttcn. The 'short [int]' notation means 'short int or short' and is used as a compact way to describe two types, short int and short, to which the same mapping applies.

typedef char T1;

type c_char T1;

typedef short T2;
typedef short int T2b;

type c_short T2;
type c_short T2b;

typedef int T3;

type c_int T3;

typedef long T4;
typedef long int T4b;

type c_long T4;
type c_long T4b;

typedef signed char ST1;

type c_signed_char ST1;

typedef signed short ST2;
typedef signed short int ST2b;

type c_short ST2;
type c_short ST2b;

typedef signed ST3;
typedef signed int ST3b;

type c_int ST3;
type c_int ST3b;

typedef signed long ST4;
typedef signed long int ST4b;

type c_long ST4;
type c_long ST4b;

typedef unsigned char UT1;

type c_unsigned_char UT1;

typedef unsigned short UT2;
typedef unsigned short int UT2b;

type c_unsigned_short UT2;
type c_unsigned_short UT2b;

typedef unsigned UT3;
typedef unsigned int UT3b;

type c_unsigned_int UT3;
type c_unsigned_int UT3b;

typedef unsigned long UT4;
typedef unsigned long int UT4b;

type c_unsigned_long UT4;
type c_unsigned_long UT4b;

typedef float FT1;

type c_float FT1;

typedef double FT2;

type c_double FT2;

typedef long double FT3;

type c_long_double FT3;

typedef struct BS1
{
    unsigned char data;
    long int bits;
}
BS1;

typedef struct BS2
{
    char data;
    int bits;
}
BS2Tag;

struct BS3
{
    signed char data;
    short int bits;
};

type record BS1
{
    c_unsigned_char data,
    c_long bits
}

type record BS2
{
    c_char data,
    c_int bits
}

type BS2 BS2Tag;

type record BS3
{
    c_signed_char data,
    c_short bits
}

struct WORDREGS
{
    unsigned short ax, bx;
};

struct BYTEREGS
{
    unsigned char al, ah, bl, bh;
};

union REGS
{
    struct WORDREGS x;
    struct BYTEREGS h;
};

type record WORDREGS
{
    c_unsigned_short ax,
    c_unsigned_short bx
}

type record BYTEREGS
{
    c_unsigned_char al,
    c_unsigned_char ah,
    c_unsigned_char bl,
    c_unsigned_char bh
}

type record REGS
{
    WORDREGS x optional,
    BYTEREGS h optional
}

typedef enum DAY
{
    saturday,
    sunday = 0,
    monday,
    tuesday,
    wednesday,
    thursday,
    friday
};

type c_int DAY;

const c_int DAY_saturday := 0;
const c_int DAY_sunday := 0;
const c_int DAY_monday := 1;
const c_int DAY_tuesday := 2;
const c_int DAY_wednesday := 3;
const c_int DAY_thursday := 4;
const c_int DAY_friday := 5;

Nested type definitions

Nested type definitions can be encountered at least inside C union, struct.

typedef union {
  struct {
    unsigned short ax;
    unsigned short bx;
  } x;
  struct {
    unsigned char al;
    unsigned char ah;
    unsigned char bl;
    unsigned char bh;
  } h;
} ALT_REGS;

type record ALT_REGS
{
    record {
      c_unsigned_short ax,
      c_unsigned_short bx
    } x optional,
    record {
      c_unsigned_char al,
      c_unsigned_char ah,
      c_unsigned_char bl,
      c_unsigned_char bh
    } h optional
}

struct  STRUCT_A
{
    int x;
    struct
    {
      int y;
    } z;
};

type record STRUCT_A
{
    c_int x,
    record
    {
      c_int y
    } z
};

Future enhancements

• C bit fields in struct
• arrays
• pointers

Slide show presentation (PDF)

You are welcome to visit our comprehensive presentation titled C testing using TTCN-3 in the form of a short slide show in the PDF format.

The slide show is available herePDF (155 KB).

You need Adobe Acrobat Reader to view the presentation.

Contact us

Please contact us to obtain more information about ANSI C to TTCN-3 codec (adapter) and ANSI C to TTCN-3 converter for testing C applications based on the above specification.