Cellular Network Infrastructure

h1. Titan TTCN3 Notes

Some notes about developing in Titan TTCN3, specifically regarding test cases in the Osmocom universe.

h1. Building / Using test cases

h2. Dependencies

* You'll need recent enough eclipse-titan installed: 8.0.0 or later recommended.

** if you're using Debian packages, you might run into a compile error "The version of GCC does not match the expected version". If you do, it is suggested to use MAKEDEPEND_RUN define to workaround the issue. Alternatively you can edit @/usr/include/titan/cversion.h@ and comment out the related @#error@ line.

** there's a build for Debian 9.0 available from our @osmocom:latest@ feed, see https://obs.osmocom.org/package/show/osmocom:latest/eclipse-titan

* You'll need a checkout/clone of @https://gerrit.osmocom.org/osmo-ttcn3-hacks/@

h3. Titan Modules required

The @osmo-ttcn3-hacks@ depend on a variety of other TTCN-3 modules that will be automatically cloned by the make files included, see the @deps/@ sub-directory.

h2. Test run

For example, to run sysinfo tests do the following:

* adjust BASEDIR in sysinfo/gen_links.sh to match your environment

* adjust test configuration in sysinfo/Test.cfg if necessary

<pre>

cd sysinfo

./gen_links.sh

./regen_makefile.sh

make -j1 compile && make -j8

cd ..

./start-testsuite.sh sysinfo/Test sysinfo/Test.cfg

</pre>

See also https://gitea.osmocom.org/osmocom/docker-playground/src/branch/master/ttcn3-nitb-sysinfo

h3. Log files

you will receive log files in the current working directory.  You can use the @ttcn3_logmerge@ tool to merge multiple log files based on their timestamps, and you can use the @ttcn3_logformat@ tool to do some human-friendly formatting of the log files.  Harald often runs his test suite like:

<pre>

rm -f *.log && make -j1 compile && make -j8 && ../start-testsuite.sh MGCP_Test MGCP_Test.cfg && ttcn3_logformat *.log

</pre>

h1. Development related bits

h2. ttcn3 import statements

Calling the shell scripts to create symlinks is necessary because the titan compiler has to see all related files at once.

Be careful when you're adding new import statements to files residing in the library/ subdirectory - those might not get symlinked to all test subdirs yet, and might cause compile errors for some tests!

h2. Learning TTCN3

A good set of slides about TTCN3 can be found in:

* http://download.eclipse.org/titan/TTCN3_Course_PartI_EclipseLicensed.pdf

* http://download.eclipse.org/titan/TTCN3_Course_PartII_EclipseLicensed.pdf

* http://www.ttcn-3.org/files/Titan_TTCN3_course.pdf

* https://download.eclipse.org/titan/UserGuide.pdf

* https://download.eclipse.org/titan/ReferenceGuide.pdf

See also http://www.ttcn-3.org/index.php/learn/tutorials.

h2. Speedup local builds with ccache:

There's a patch in gerrit to use ccache if it is found in the build system, which provides a speedup factor of around x10.

Patch can be found in: https://gerrit.osmocom.org/#/c/7601/

Upstream should be contacted to request for inclusion of a flag to remove the "generated date" as a comment in the generated code, which prevents ccache to work fine out of the box (the provided gerrit patch workarounds this issue).

h2. RAW coder

A lot of the messages (GSMTAP, LAPDm, L1CTL, ...) are described using the Titan extensions to the TTCN-3 type language and the associated RAW coder.

Section 4.23 of the _Programmer's Technical Reference Guide for the TITAN TTCN-3 Toolset_ contains the description of this RAW coder.

See https://github.com/eclipse/titan.core/blob/master/usrguide/referenceguide/4-ttcn3_language_extensions.adoc#raw-encoder-and-decoder.

h3. FIELDORDER

This determines the order of fields within a record or set type.

In (not only) GSM specs, typically the messages are described from first field at top to the last field at the bottom, so the logical choice here is to set "FIELDORDER(msb)" as we do in the GMS_Types.ttcn and other files.  However, there's one CAVEAT: In GSM 04.08 (and derived specs), Information Elements with 1/2 (4bit) length are ordered un-intitively.

Example: TS 44.018 SYSTEM INFORMATION TYPE 4:

 * L1 Pseudl Length (1)

 * protocol descriptor (1/2)

 * skip indicator (1/2)

 * Message Type (1)

which then translates to:

<pre>

        type record RrHeader {

                L2PseudoLength  l2_plen,

                uint4_t         skip_indicator,

                uint4_t         rr_protocol_discriminator,

                RrMessageType   message_type

        } with { variant "FIELDORDER(msb)" };

</pre>

Note the skip_indicator and rr_protocol_discriminator fields are swapped in their order compared to the spec!

h3. fftranscode

Our RANAP ttcn3 tests require libfftranscode, which can be found at: https://downloads.osmocom.org/binaries/libfftranscode/

When it is missing, the error message looks like this:

<pre>

RANAP_EncDec.cc:7:10: fatal error: fftranscode/transcode.h: No such file or directory

    7 | #include <fftranscode/transcode.h>

      |          ^~~~~~~~~~~~~~~~~~~~~~~~~

compilation terminated.

make: *** [Makefile:180: RANAP_EncDec.o] Error 1

</pre>

See also [[Titan_TTCN3_Testsuites]]