FFFISCom/Euroradio/C V2.0.

0 User
Guide
FFFISCom/Euroradio/C V2.0.0 User Guide
Table of Contents
1. Introduction ....................................................................................... 1
1.1. What this document is... ............................................................. 1
1.2. What this document is not... ........................................................ 1
2. Installation ........................................................................................ 2
2.1. Installation procedure ................................................................ 2
3. The basic concepts .............................................................................. 3
3.1. A pure library ........................................................................... 3
3.2. Library Architecture .................................................................. 3
3.2.1. Decomposing the functionality of the application layer .................. 4
3.3. Configuration structures ............................................................. 4
3.4. Networks ................................................................................. 5
3.5. Safety connections .................................................................... 5
3.6. Handling the physical layer ......................................................... 6
3.7. Application layer messages encoding/decoding ............................... 6
3.8. Timing .................................................................................... 6
3.9. Threading ................................................................................ 7
3.10. Error-detecting codes ............................................................... 7
3.10.1. Object Protection Implementation ............................................ 7
3.10.2. Object Protection Levels ........................................................ 8
3.10.3. Object Protection recomendation ............................................. 8
4. The source files .................................................................................. 9
4.1. The header files to include .......................................................... 9
4.2. The functions to provide ............................................................. 9
4.2.1. Trace Function ....................................................................... 9
4.2.2. Assertion Failed function ......................................................... 9
4.3. Compiling the library ............................................................... 11
4.3.1. Protection Level ................................................................... 12
4.3.2. Traces ................................................................................ 12
4.3.3. DES Provider ...................................................................... 13
5. Typical usage ................................................................................... 14
5.1. SFM Application .................................................................... 14
5.1.1. SFM Initialization ................................................................ 14
5.1.2. SFM Main Loop ................................................................... 14
5.2. CFM Application .................................................................... 18
5.2.1. CFM Initialization ................................................................ 18
5.2.2. CFM Main Loop .................................................................. 18
5.3. Error handling ........................................................................ 19
5.4. Using the application layer codecs .............................................. 19
5.4.1. Reading application messages ................................................. 20
5.4.2. Writing application messages .................................................. 20
5.5. Sizing the library .................................................................... 20
6. How to... ......................................................................................... 21
6.1. Use my own DES function instead of the one provided with the library
.................................................................................................. 21

iv
List of Tables
3.1. ...................................................................................................... 8

v
Chapter 1. Introduction
1.1. What this document is...
This document describes the FFFFIScom/Euroradio library V2.0, its underlying concepts and im-
portant properties. It does:

• Explain the properties that are relevant for a developer who considers using the library: its rela-
tionship to threading, timing considerations, interfaces to hardware, etc.

• Explain the mapping between the subsets 037 and 026 concepts and their representation in the
library

• Provide a complete explanation of the protocol one must follow to use the library, the meaning
of the important parameters, and the sequence in which the various functions must be called.

1.2. What this document is not...

On the other hand, this document is also restricted in a number of ways:

• It is not a tutorial about the subsets 037 and 026. At least a basic knowledge of these standards
and their practical implications is assumed.

• It is not a tutorial about C either: the language, its constructs, their semantics and idiomatic uses
(such as header files, conditional compilation, etc.) are considered as prerequisite knowledge to
use this document proficiently.

• It is a user guide as opposed to a source navigation document: its aim is to explain how one can
use the library proficiently, not to provide a detailed description of the internals.

• It is not an exhaustive descriptive document on the API and its underlying data types, which are
better and more accurately explained in the HTML API documentation derived from the imple-
mentation, accessible by pointing a webbrowser at
$INSTALLDIR/doc/html/index.html. Would this documentation contradict the current
document in any way, the former is to consider more relevant, as it is generated automatically
from annotations to the source code1, and hence, is to be considered a better description of its
actual behaviour.

1For more information about the tool user for source code documentation, visit http://www.stack.nl/~dimitri/doxygen/

1
Chapter 2. Installation
2.1. Installation procedure
The library comes in the form of a single .tgz file, which must be expanded in an ad hoc directory. It
contains two subdirectories:

• src contains the source code

• doc contains the documentation, that is, this document and an api_html subdirectory which
contains the documentation from the source code

The src directory contains three subdirectories of its own:

• src/sfm contains the library source code for the SFM module

• src/cfm contains the library source code for the CFM module

• src/scl contains the library source code for the tests integrating SFM and CFM modules

Each of these directories contain, in turn, three subdirectories:

• lib/ which contains the C source files (*.c) and header files (*.h)

• test/ which contains the source code of the test infrastructure (*.c and *.h)

• example/ which contains an example application

2
Chapter 3. The basic concepts
3.1. A pure library
This library implements UNISIG Subset-037 and chapters 7 and 8 of UNISIG subset-026 (hereafter
referred to as the standard) so that a developer can write applications that communicate with other
Subset-037 compliant equipements without having to care for all the low-level technicalities de-
scribed in the standards. The entire issue of communication is addressed by a number of high-level
functions only.

The library provides ultimate flexibility, by being self-contained. It does not call any standard lib-
rary function, and furthermore, it does not perform explicit calls to a timing function, nor to hard-
ware access functions to actually send and receive data on the transmission medium.

The library also isolates safety-related functionality from non-safety-related functionality by provid-
ing two completely independent modules: the SFM (Safe Functional Module) and CFM
(Communication Functional Module). These modules support completely asynchronous communic-
ation, to support both single-process and distributed architectures.

Basically, it is the user's code's responsibility to:

• Provide the library with application-level outgoing data that must be sent on the safety connec-
tions

• Notify the library often enough to allow time-related functions (timeouts, etc.) to perform appro-
priately. Please note that this implies that the current time must be provided by the user as para-
meter to a number of the functions of the public API.

• Reliably transfer messages between the CFM and the SFM modules.

• Read the data coming from the DCE1 (Data Communication Equipment, for example a GSM-R
Modem), by means of interrupt function, polling or any other mechanism supported by his hard-
ware and supporting computing platform, and provide the raw data to the library. For more de-
tails about DCE, see http://en.wikipedia.org/wiki/Data_circuit-terminating_equipment.

• Query the library for any incoming message that has been identified as user-data

• Receive DCE connection and disconnection orders from the library and inform the library of
connection/disconnection status of the DCE.

• Send the outgoing data on the DCE when, as a result of one of the actions listed above, there is
outgoing data to be sent.

3.2. Library Architecture

The FFFIScom/Euroradio library is divided in two independent units

• The Euroradio layer, defined in UNISIG Subset-037. This layer is splitted in two independent
modules:

• The SFM (Safe Functional Module). This module isolates the Safety functionalities specified
in the Subset-037

1Throughout this document, DCE is used as a generic synonym for Modem or ISDN card, or any device used to perform phone communica-
tions used as physical transport for Euroradio communications.

3
 The basic concepts

• The CFM (Communication Functional Module), that implements the following protocol lay-
ers:

• X.224 (Transport layer)

• T.70 (Network Layer)

• HDLC (Data Link Layer)

• Coordination function

• The Application layer defined in UNISIG Subset-026 chapters 7 and 8

The Euroradio layer deals with the safe transmission of sequences of bytes; the latter with the rep-
resentation of meaningful data out of such sequences of bytes.

The FFFIScom library supports these two independent units without any coupling: application pro-
grammers can use it to send proprietary trafic on a Euroradio connection without being restricted to
ERTMS application messages as user data.

More specifically, this means that it is perfectly possible to use Euroradio to send information of a
totally different nature from what the ERTMS application layer recognizes, and conversely, the ap-
plication layer could be used to decode traffic that has been sent through entirely different means.

Since these two parts of the library are entirely decoupled, the related deliverables will be decoupled
accordingly: test, documentation, etc.

These layers are easy to track down in the code: every item related to the Euroradio protocol sub-
layers has a "ER37", "__ER__" or "Er37" prefix attached to it, followed by the sub-layer name. and
quite predictably, every item attached to the application layer has a "ER_APP", "ER__APP__" or
"ER_App" prefix attached to it.

3.2.1. Decomposing the functionality of the application

layer
The application layer - referred to as the codecs - is responsible for coding, namely, taking applica-
tion-level data structure and turning them into sequences of bytes according to the standard, and de-
coding, namely, taking a sequence of bytes, and turning it into an application-level data structure.

It is intuitively clear that decoding involves a form of validation: of all the possible sequences of
bytes, of all lengths and contents, only a tiny fraction is valid for decoding.

What is less clear, is the fact that the application layer of this library will distinguish between two
forms of validity checks to be performed:

• It will first ensure that messages are structurally correct, in the sense that it can interpret the en-
tire sequence of bytes and explode it into messages, etc.

• It will then ensure that atomic - non-composite - values are valid, that is, they lie between the
corresponding validity bounds defined in the standard.

The two levels of validations are separate, implemented as separate functions, so that the decoding
process does not stop when an invalid value has been found, thereby allowing for more fine-grained
control on the process.

3.3. Configuration structures

4
 The basic concepts

The library defines the following configuration structures:

• ER37_SFM_Network_Parameters, containing HDLC-related configuration variables.

• ER_Safety_Connection_Config_Struct, containing Safety-related configuration vari-

ables.

When provided to a function, arguments of the configuration structures are copied into the network
and/or connection if required. In other words, after having been passed as parameter, the configura-
tion structures can be changed, discarded if stored as a local variable, etc. without altering the sub-
sequent behaviour of the networks and connections that have been initialized before.

The meaning and recommended value of each configuration variable can be found in the HTML
API documentation, in the sections covering the two structures.

3.4. Networks
The Euroradio protocol stack is made of 4 independent sub-layers piled up in the following order:

• Safety

• X.224 (Transport layer)

• T.70 (Network layer)

• HDLC (Data Link layer)

The FFFIScom/Euroradio library splits this protocol stack in two parts:

• The SFM module, containing all Safety-related functionality and acting as a controller for the
CFM module.

• The CFM module, containing the three bottom layers in charge of transport, network, data link
layers and the coordination function.

The non-safety components of the protocol stack are represented by the Network abstraction.

A Network represents a communication channel between two Euroradio-connected systems. For ex-
ample, an EVC connected to a single RBC needs one Network. This network can support one phys-
ical connection channel (For example, a GSM-R connection), but several Safety connections(See
Section 3.5, “Safety connections”)

As each Network instance is related to a single physical communication channel, a train having two
GSM-R modems, and wanting to establish Euroradio safety connections to two different RBCs must
have two distinct Network instances. Safety connections created on different Network instances will
be totally independent.

As the SFM modules acts as a controller for the CFM module, its public API exposes functionalities
to initialize, connect, disconnect and dispose Networks. Typical usage is explained in details in
Chapter 5, Typical usage

3.5. Safety connections

The safety connection abstraction represents a Euroradio safety connection.

It contains the ncessary information to establish a safety connection and to exchange user data:

5
 The basic concepts

• Low Priority User Data with safety MAC procedure

• High Priority User Data without safety procedure

The relationship between Networks and Safety connections is a one-to-many relationship: one net-
work can contain several Safety Connections. Typical usage is explained in details in Chapter 5,
Typical usage

3.6. Handling the physical layer

API functions are provided to handle all events related to the physical layer. These encompass the
following;

• Receiving DCE connection or disconnection order from the library

(ER37_Modem_Event_Connect_Req, ER37_Modem_Event_Connect_Ind,
ER37_Modem_Event_Disconnect_Req)

• Receiving data to be sent on the DCE from the library

(ER37_Modem_Event_Data_To_Modem)

• Inform the library about connection/disconnection status of the DCE

(ER37_Modem_Event_Disconnect_Ind, ER37_Modem_Event_Connect_Con)

• Inform the library about data coming from the DCE

(ER37_Modem_Event_Data_From_Modem)

Using the following functions, the user can, for each network separately, receive or provide the
above mentioned events to the library:

• ER37_CFM_Network_Get_Event(...)

• ER37_CFM_Network_Put_Event(...)

The sequence in which these functions must be invoked with specific events is detailed in Chapter 5,
Typical usage.

When informing the library of incoming data using ER37_CFM_Network_Put_Event(...),

the user is free to pass any number of bytes up to the size of the bottom layer FIFO size. See Sec-
tion 5.5, “Sizing the library” for more information about library sizing issues.

3.7. Application layer messages encoding/de-

coding
The library provides functions to perform all tasks related to Subset-026 messages , packets and
variables reading, writing and validation. For each application message and packet, the library de-
clares a structure. Typical application message encoding/decoding is explained the section Sec-
tion 5.4, “Using the application layer codecs”.

3.8. Timing
The library has no internal clock, nor does it access an external clock behind the scenes. The only
source for timing information it will ever use is the Now parameter declared in most public functions
except for the application layer which only provides time-insensitive coding and decoding services.

6
 The basic concepts

The Now parameter is a 32-bit unsiged integer, representing the amount of miliseconds elapsed since
the start of the system using the library.

It is the user's responsibility to ensure that the time value given to the library is monotonously in-
creasing and accurate. Monotously increasing means that the time values must increase or stay the
same, they cannot decrease (With the exception of the 32-bit overflow).

It is also the user's responsibility to ensure the library is called often enough to guarantee that all
time-related behaviour is correct (timeouts, etc.)

3.9. Threading
The library is stateless in the sense that all the information it maintains across function calls are
stored in the ER37_SFM_Object and ER37_CFM_Object structures.

However, as these objects hold data related to library state handling and inter-module communica-
tion, multi-thread usage is discouraged, as it could provoke serious concurrency problems.

3.10. Error-detecting codes

The FFFFIScom/Euroradio library is extremely robust, and makes very conservative use of the facil-
ities provided by the C language in order to reduce the risk of software failure as much as possible.
However, this does not prevent the library from being potentially vulnerable to third party code
linked into the same application, and hence, the same address space.

In order to address this issue, the libray provides error detecting code that protects the library objects
against:

• Using objects that where not properly initialized.

• Using objects that are not library objects.

• Using objects that have been modified outside any library function

The protected objects are:

• ER37_CFM_Object

• ER37_IMC_Object

• SFM_Connection

• ER37_SFM_Network

• ER37_SFM_Object

3.10.1. Object Protection Implementation

A 32 bits integer (Beginning_Signature) is declared as the first field of the protected object.

A 32 bits integer (Ending_Signature) is declared further in the protected object.

The ending signature holds the CRC32 of all the object bytes between the beginning signature
(inclusive) and the ending signature (exclusive).

When an object is created (for an example see the ER37_SFM_Initialize_Library function)

the actual object initialisation is performed and then the CRC32 is computed and stored in the end-

7
 The basic concepts

ing signature. Later when any public function is called with the object as parameter, a newly CRC32
is computed and compared to the stored one in the ending signature.

If the computed CRC32 does not match the stored one in the ending signature, the functions returns
an specific error code. User application should stop all processing since the object has been corrup-
ted an safe processing is not guaranteed anymore.

If the computed and stored CRCs are equal, the following steps are performed:

1. The protection is removed y invalidating the ending signature (ending signature is bitwise neg-
ated).

2. The specific code of the called function is performd.

3. A new protection couple is created: The beginning signature is incremented and a CRC32 is
computed and stored in the ending signature.

3.10.2. Object Protection Levels

Protection is always enabled and cannot be disabled.

However the user has the possibility to choose from 3 different protections levels wich have differ-
ent qualities and different impact on performances.

Table 3.1.
Protection Level Detects unitialized Detects invalid ob- Detects memory Computational
objects jects corruption overhead
Minimal yes yes no neglectable
Standard yes yes partial low
Extended yes yes full high

The first level ensures that objects passed to the library have been properly initialized. The computa-
tional overhead is limited to compute a CRC32 on one 32 bits integer. However, this level does not
detect that the passed object has been corrupted.

The second level offers the same protection than the first one while adding the ability to detect that
some of the internal variables inside the object have been changed outside of a library function
call.The computational overhead is higher as the CRC32 is computed over more bytes.

The last level is of course fairly computationally intensive, since the library objects may contain
FIFO's wich may be fairly big. A safety connection compiled with a maximum of 2 messages will
raise to more than 2000 bytes. Computing a CRC32 requires that the entire data structure is scanned
twice on every function call that deals with the object: once for protection verification, once for
(re)protecting the object. The advantage is that any memory corruption is detected.

3.10.3. Object Protection recomendation

We recommend to use the Standard object protection level.

8
Chapter 4. The source files
4.1. The header files to include
In an application which must interact with the library, depending on the module used (CFM or
SFM), the following files must be included:

Files to include in the SFM application:

• er37_sfm_api.h contains the prototypes for the functions required to manage the library,
network and safety connection objects.

• er_app.h contains the application-level codecs prototypes. If you wish to use the library for
the two lower layers only, using your own application messages rather than the standard subset-
026 messages, you do not need to include this file.

Including any of these header files will result in including other header files. The two first are basic-
ally all you need for a SFM application.

Files to include in the CFM application:

• er37_cfm_api.h: contains the prototypes for the functions required to manage the library
and interact with the IMC and the modems.

4.2. The functions to provide

Three functions must be implemented by the user and linked to his application.

1. The Trace function

2. The failed assertion function

3. The encryption key lookup function (SFM ONLY)

4.2.1. Trace Function

If the library traces are enabled (using the ER_ENABLE_TRACES define), the library provides ex-
tended information of its internal states, incoming and outgoing messages.

This information is processed inside the er_trace module. This module calls an external function that
can perform the actual output. Next code example shows an example of
ER37_USER_Trace_Function function implementation.

void ER37_USER_Trace_Function (const erTIME Now , const erCHAR * Channel, const

{
print (" %15s %8lu %s\n", Channel, Now, Format);
}

4.2.2. Assertion Failed function

Assertions are computational conditions that must be true in any circumstances. Whatever the user

9
 The source files

ot network input may be, the library ensures that some vital internal variables have a safe value.

In order to ensure these internal states are valid, the code is populated with ER_Assert macros that
will ensure that the given expression is true.

ER_Assert (pDst >= pConn->Assembler);

ER_Assert (pDst < pConn->Assembler +
SIZEOF(pConn->Assembler) );

If the given expression is not true, a severe and irrecoverable error has occured. In that case, the lib-
rary calls a user defined function, ER_Assertion_Failed, that is supposed to catch the error
and stop the user aplpication in a fail safe way.

The user defined function ER_Assertion_Failed may not return.

4.2.2.1. Simple implementation

The simplest ER_Asssertion_Failed implementation:

void ER_Assertion_Failed (const erCHAR * const File_Name,

const erINT32 Line_Nr,
const erCHAR * const Expression)
{
printf ("ASSERTION FAILED %s (%d): %s\n",
File_Name,
Line_Nr,
Expression));
exit (1);
}

This implementation shall terminate the application and return to the host operating system, if any.

4.2.2.2. Example using setjmp/longjmp

One way to implement the ER_Assertion_Failed is the usage of the setjmp/longjmp function pairs.

The main application saves the environment (setjmp) before any library call is performed.

The ER_Assertion_Failed restores this environment (longjmp) in order to return to the calling ap-
plication.

void ER_Assertion_Failed (const erCHAR * const File_Name,

const erINT32 Line_Nr,
const erCHAR * const Expression)
{
/* we also should store this event in NVRAM */
printf ("ASSERTION FAILED %s (%d): %s\n",
File_Name,
Line_Nr,
Expression));
/* return to the beginning of the application */
longjmp (assert_jmp_buffer, 1);
}

#include <setjmp.h>
/* define a global setjmp/longjmp buffer */

10
 The source files

jmp_buff _assert_jmp_buffer;
void main (void)
{
int res;
res = setjmp (assert_jmp_buffer);
if (res == 0)
{
ER37_SFM_Initialize_Library(...);
/* here comes the application */
}
else
{
/* We are returning from an ER_Assert that failed */
/* Log the Error */
/* Then, safely shutdown */
}
}

4.3. Compiling the library

The library is written in pure C, using the widely available C89 standard.

The library is developped with the most restrictive compiler settings available at development time,
specifically focused on avoiding any compiler warnings. Additional tools like Splint and Lint per-
formed advanced verifications on the code.

The ER37 Library accepts some compilations options that allow the user to fit his particular needs.

Compilations options may be divided in two groups:

1. Optional features options : Assertions, Protection Level, DES provider.

2. Dimentional options: Number of networks, Number of Safety connections, number of Safety

LP messages, number of HP messages and number of IMC messages.

Options in the first group must be manually selected by the user. There is no default value.

Options in the second group have default values that the user may override. Default values are indic-
ated in the API documentation for file er37_sizes.h.

Options in both groups may be specified in two different ways:

• As compiler directives (usually -D... flag on compiler's options)

• As C standard defines inside a user provided er37_user.h

In order to enable a user defined er37_user.h include file, a single compiler must be defined:

-DER_ENABLE_USER_INCLUDE

Compiling without er37_user.h.

gcc -DER_ENABLE_TRACES
-DER_ENABLE_STANDARD_OBJECT_PROTECTION
-DER_USE_LIBRARY_DES

11
 The source files

-DER37_MAX_KEYS_IN_DICTIONNARY=30UL
-DER37_MAX_SAFETY_CONNECTIONS=10UL
-DER37_MAX_SAFETY_MESSAGES=2UL
-DER37_MAX_SAFETY_MESSAGES_HP=2UL
-I.
*.c

Compiling with er37_user.h

The user must create a er37_user.h file like this

#ifndef ER_USER_INCLUDE_H_
#define ER_USER_INCLUDE_H_
#define ER_ENABLE_MINIMAL_OBJECT_PROTECTION
#define ER_ENABLE_TRACES
#define ER_USE_LIBRARY_DES
#define ER37_MAX_SAFETY_NETWORKS 2UL
#define ER37_MAX_SAFETY_CONNECTIONS 10UL
#define ER37_MAX_SAFETY_MESSAGES 2UL
#define ER37_MAX_SAFETY_MESSAGES_HP 2UL
#define ER37_IMC_MAX_FIFO_SIZE 5UL
#endif

And compile the sources:

gcc -DER_ENABLE_USER_INCLUDE
-I.
*.c

4.3.1. Protection Level

One, and exactly one of the following must be defined:

1. ER_MINIMAL_OBJECT_PROTECTION

2. ER_STANDARD_OBJECT_PROTECTION

3. ER_EXTENDED_OBJECT_PROTECTION

4.3.2. Traces
One, and exactly one, of the following must be defined:

1. ER_ENABLE_TRACES

2. ER_DISABLE_TRACES

If the first option is choosen, it is the responsability pro provide an external implementation for the
function:

void ER37_USER_Trace_Function (erTIME Now,

const erCHAR * const Channel,

12
 The source files

const erCHAR * const Format);

4.3.3. DES Provider

One, and exactly one of the following must be defined:

1. ER_USE_LIBRARY_DES

2. ER_USE_USER_DES

If the second option is choosen, it is the responsability of the user to provide a valid implemebtation
of these two functions:

void ER_DES_Crypt(const ER_DES_Coder_Struct * const pCoder,

erBYTE * const in,
erBYTE * const out);
void ER_DES_Key_Schedule(ER_DES_Coder_Struct * const pCoder,
const erBYTE key[8],
ER_DES_Operation_Enum mode);

13
Chapter 5. Typical usage
This chapter lists the steps that your application program should follow in order to interact grace-
fully with the library. The example application er37_example_main.c available in the HTML
documentation (and as source code) provide a complete and operation example of simple EVC and
RBC applications using the library.

In the provided example, the communication between the CFM and SFM modules and between the
two peer CFMs (the EVC CFM and the RBC CFM) are implemented on top of TCP/IP, in order to
provide a working performing real ansynchronous communication.

The following sections detail step-by-step the various API calls that the EVC and RBC applications
must perform, as well in the SFM as in the CFM module/host.

5.1. SFM Application

This section details every API call needed in the application hosting the SFM module of the library.

The SFM application must perform the following sequence of tasks:

5.1.1. SFM Initialization

The first API call that the user must invoke is ER37_SFM_Initialize_Library. This must be
done prior to any other CFM function call.

Once initialization has been ordered, the SFM will send an IMC message to its peer CFM, and wait
for an IMC message from its peer CFM.

In order for the IMC messages to be exchanged, the user application must invoke ciclycally the fol-
lowing functions:

• ER37_SFM_Get_IMC_Message

• ER37_SFM_Put_IMC_Message

• ER37_SFM_Process

• ER37_SFM_Get_Library_Status

Once these two messages have been exchanged, the SFM is ready to enter its main application loop.
This is signalled by the user when the library status is ER37_LIB_State_OPERATIONAL.

In case of configuration or version differences between the CFM and SFM, the library status will
become ER37_LIB_State_ERROR. In that situation, user code should go to safe state.

The example application module er37_example_sfm.c illustrates the CFM initialization pro-
cedure in the function example_initialize_sfm_library.

5.1.2. SFM Main Loop

Once the SFM is succesfully initialized, it can enter its main application loop. Inside the application
main loop, different type of operations need to be performed:

1. Library status monitoring

2. IMC communication

14
 Typical usage

3. Network and Safety connections management

4. Sending and receiving Application messages

5. Receiving Safety indication reports

5.1.2.1. Library status monitoring

Inside the main SFM loop, the user code must call the function
ER37_SFM_Get_Library_Status at regular intervals. If the status changes from
ER37_LIB_State_OPERATIONAL, the user code must put the SFM application in a safe state.

The following reasons might cause a status transition from ER37_LIB_State_OPERATIONAL:

• An internal error in the SFM

• A memory corruption that has been detected

• An incompatible CFM (Different number of networks, different number of connections per net-
work or different library version)

• An error in the CFM propagated in the SFM through the ICM

See for a practical example the function example_get_library_status in

er37_example_fsm.c.

5.1.2.2. IMC communication

The user code has the responsibility for ensuring reliable ICM communication between the SFM
and the CFM module.

This means that inside the main SFM application loop, the user code should provide the messages
coming from the CFM to the SFM using ER37_SFM_Put_IMC_Message, and provide the mes-
sages targeted to the CFM using ER37_SFM_Get_IMC_Message.

See for a practical example the functions example_imc_to_tcpip and ex-

ample_tcpip_to_imc in er37_example_fsm.c.

5.1.2.3. Network and Safety connections management

Network and Safety connections lifecyle involves several tasks: connection establishment, connec-
tion status monitoring, connection release and connection re-use.

5.1.2.3.1. Connection establishment

In order to establish Safety connections to a Euroradio peer application, the user code must first ini-
tialize and connect a Network.

As network initialization and connection impacts the CFM, these operations are asynchronous. They
involve the following sequence of operations:

1. Network initialization using ER37_SFM_Initialize_Network.

2. Network initialization monitoring using ER37_SFM_Get_Network_Status

3. If the SFM is the connection initiator (I.e. the party which calls the other party), Network con-
nection using ER37_SFM_Connect_Network. Network connection can only be performed after
successful network initialization. Network connection is an optional step that can be performed
automatically by the the SFM when the user code initiates Safety connection establishment us-

15
 Typical usage

ing ER37_SFM_Connect_Connection.

4. If the SFM is the connection initiator, monitoring the Network connection status using
ER37_SFM_Get_Network_Status, until it is ER37_SFM_Network_Status_CONNECTED.

Once a network is succesfully initialized, one or more Safety connections can be created in associ-
ation with that network, using the following operations:

1. Connection initialization using ER37_SFM_Initialize_Connection.

2. Connection initialization monitoring using ER37_SFM_Get_Connection_Status

3. If the SFM is the connection initiator (I.e. the party which calls the other party), Connection es-
tablishment using ER37_SFM_Connect_Connection. Connection establishment can only be
performed after successful connection initialization.

4. If the SFM is the connection receiver, the user code must monitor the status of the connection
until it is ER37_SFM_Connection_Status_ACCEPT_PENDING. This status means that a peer
Safety connection has started Safety connection establishment procedure.

At that moment, the user code can check the incoming connection's ETCS ID and ETCS ID
Type using the ER37_SFM_Get_Safety_Connection_Properties function, and accept it using
the ER37_SFM_Accept_Safety_Connection function.

5. If the SFM is the connection initiator, monitoring the Network connection status using
ER37_SFM_Get_Network_Status, until it is ER37_SFM_Network_Status_CONNECTED.

See for a practical example the function example_main_loop in er37_example_fsm.c.

5.1.2.3.1.1. Connection Creation Checks

The following functional checks are performed when the user code initializes a new Safety connec-
tion:

• If all connections are already initialized, the ER37_Connection_Create_NO_SPACE error code

is returned.

• All safety connections created on a same Network must have the same ETCS ID and ETCS ID
type values. They also must have a different Application Type value. If one of these two condi-
tions is not not fullfilled, the ER37_Connection_Create(...) will return
ER37_SFM_Initialize_Safety_Connection_INVALID_PARAMS

5.1.2.3.2. Connection status monitoring

The status of a connection must be monitored using the function
ER37_SFM_Get_Safety_Connection_Status.

A transition from the ER37_SFM_Connection_Status_CONNECTED to the

ER37_SFM_Connection_Status_DISCONNECTING or
ER37_SFM_Connection_Status_DISCONNECTED state is the indication that one of the following
events has occured:

1. The ER37_SFM_Disconnect_Safety_Connection function has been invoked.

2. The peer Safety connection has requested disconnection

3. An error in the CFM protocol layers has provoked transport connection disconnection

16
 Typical usage

In order for the user code to know what happened, the SFM publish several variables in the
ER37_SFM_Connection_Status_Struct:

• Outgoing_Disconnect_Reason

• Outgoing_Disconnect_SubReason

• Incoming_Disconnect_Reason

• Incoming_Disconnect_SubReason

5.1.2.3.3. Connection And Network Release

Prerequisite: you have a safety connection which is in connected state.

Once the user code wants to disconnect the connection, he can issue a
ER37_SFM_Disconnect_Safety_Connection call.

This call orders the safety connection to disconnect at the next ER37_SFM_Process call. It is im-
portant to check the ER37_Connection_Disconnect(...) return value is
ER37_Connection_Disconnect_OK.

Otherwise, the disconnection order may not have been transmitted to the connection if the internal
FIFO of the safety connection is full, indicated by a
ER37_SFM_Disconnect_Safety_Connection_FIFO_FULL return value.In that case, the user code
should retry after processing the SFM.

Once the user has successfully ordered the disconnection, he should invoke
ER37_SFM_Process(...) until both Safety connection status and Transport connection status
are disconnected.

Inside the library, it means that the safety connection in the SFM and the associated X.224 connec-
tion in the CFM have been disconnected.

At that moment, the network can be safely disconnected, using the

ER37_SFM_Disconnect_Network function, or be left open for Safety connections that might still be
in connected status on this Network.

5.1.2.3.4. Connection And Network Recycling

Networks and connections can be reused after the connection and network have been disconnected.
When the user code wants to re-use them, they must first be disposed using the
ER37_SFM_Dispose_Network and ER37_SFM_Dispose_Connection functions, then initialized
again like explained in the above procedure.

5.1.2.4. Sending and receiving Application messages

Sending and receiving application data can only be performed on successfully established Safety
conections, using the ER37_SFM_Send_Message, ER37_SFM_Send_HP_Message,
ER37_SFM_Receive_Message and ER37_SFM_Receive_HP_Message functions.

The user is free to transport any kind of data using the high and low-priority data sending and re-
ceiving services. It can use the Subset-026 application codecs provided with the library (See Sec-
tion 5.4, “Using the application layer codecs”for a complete explanation), or decide to send any oth-
er proprietary data.

The only limitation is the size of the data that can be sent in the high and low priority services.

TODO speak about FIFO fulls.

See for a practical example the function example_main_loop in er37_example_fsm.c.

17
 Typical usage

5.1.2.5. Receiving Safety indication reports

Aside of incoming application messages, the user code can also be notified on incorrect Safety
MAC occuring in incoming Safety messages, using the ER37_SFM_Receive_Report_Indication
function.

See for a practical example the function example_main_loop in er37_example_fsm.c.

5.2. CFM Application

This section details every API call needed in the application hosting the CFM module of the library.

The CFM application must perform the following sequence of tasks:

5.2.1. CFM Initialization

The first API call that the user must invoke is ER37_CFM_Initialize_Library. This must be
done prior to any other CFM function call.

Once initialization has been ordered, the CFM will send an IMC message to its peer SFM, and wait
for an IMC message from its peer SFM.

In order for the IMC messages to be exchanged, the user application must invoke ciclycally the fol-
lowing functions:

• ER37_CFM_Get_IMC_Message

• ER37_CFM_Put_IMC_Message

• ER37_CFM_Process

• ER37_CFM_Get_Library_Status

Once these two messages have been exchanged, the CFM is ready to enter its main application loop.
This is signalled by the user when the library status is ER37_LIB_State_OPERATIONAL.

In case of configuration or version differences between the CFM and SFM, the library status will
become ER37_LIB_State_ERROR. In that situation, user code should go to safe state.

The example application module er37_example_cfm.c illustrates the CFM initialization pro-
cedure in the function example_initialize_cfm_library.

5.2.2. CFM Main Loop

Once CFM initialization is completed, the CFM can enter its application main loop. The application
main loop is similar to the CFM initialization loop, with the additional management of events to and
from the modems.

The user application must invoke ciclycally the following functions:

• ER37_CFM_Get_IMC_Message

• ER37_CFM_Put_IMC_Message

• ER37_CFM_Get_Modem_Event

• ER37_CFM_Put_Modem_Event

18
 Typical usage

• ER37_CFM_Process

• ER37_CFM_Get_Library_Status

The user code should keep performing the CFM Main loop until the library status is
ER37_LIB_State_ERROR or when its host application is terminated.

The example application module er37_example_cfm.c illustrates the CFM initialization pro-
cedure in the function example_main_loop

5.2.2.1. Modem FIFO Full handling

Three types of events coming from the DCE (For example, GSM-R Modem or ISDN connection)
must be provided to the relevant network using the ER37_CFM_Put_Modem_Event fucntion:

• DCE connection successfully established: ER37_Modem_Event_Connect_Con

• DCE connection indication: ER37_Modem_Event_Connect_Ind

• DCE disconnection: ER37_Modem_Event_Disconnect_Ind

• Incoming data: ER37_Modem_Event_Data_From_Modem

The function ER37_CFM_Put_Modem_Event(...) can return a

ER37_CFM_Put_Modem_Event_FIFO_FULL error in case the library internal data structures
for that network are full.

In the case of a ER37_Modem_Event_Data_From_Modem, some of the bytes passed to the

Put_Bytes call can already be processed by the HDLC layer, but the are discarded because the
HDLC incoming FIFO is full.

The user should discard the passed bytes, Process(...) the CFM again and keep passing in-
coming bytes to the network. The HDLC protocol layer will automatically re-assemble and require
missing frames from the HDLC connection peer.

In the case of a ER37_Network_Put_Event_Fifo_Full error after passing a

ER37_Modem_Event_Disconnect_Ind, the user should Process(...) the CFM again
and keep passing the event to the network, until successful.

5.3. Error handling

Each function of the SFM and CFM API has a unique return type, modelled as an enumeration.

Having one different enumeration for each function call ensures that the user code, if using quality-
assurance tools (like splint for instance), processes all possible return codes for each function1.

One question arises when processing these return codes is: what is the meaning of each one, and
what should the user code do in case of a non-OK return code? Put the application in a safe state?
Try again until success?

No universal answer can be given to that question. The reader is advised to look in the HTML API
documentation, which contain suggested user action for each value of each API return code enumer-
ation.

5.4. Using the application layer codecs

1See http://www.splint.org/ for more details

19
 Typical usage

The application message encoders and decoders, also known as codecs, provide high-level functions
and strcutures for every Subset-026 application message and packet.

5.4.1. Reading application messages

To read an application message from a sequence of bytes, one should use the function
ER_APP_Read(...). This function will fill in a ER_APP_Packet_Union structure that con-
tains the decoded message. The Header.Type field of the decoded message structure contains the
type of the decoded message. This type can be any of the ER_APP_Packet_Enum elements.
UNISIG Subset-026 messages can contain variables and/or packets. In order to read the packets
contained in the message, the user can check, for each packet to the message structure, the Type
field. If this field is different than ER_APP_Packet_None, this signals that the packet is con-
tained in the message.

NOTE: in the UNISIG Subset-026 specifications, a distinction is made between messages and pack-
ets, message containing variables and packets. In the library, both concepts are merged in packets.

5.4.2. Writing application messages

To write an application message, the user must first initialize the ER_APP_Packet_Union struc-
ture, by using the specialized initialization function for the desired message type. For example, if the
user wishes to write a new MA Request message, the function to use if
ER_Init_APP_MA_Request(...).

After message initialization, the user can fill the various message variables, and initialize and spe-
cify the included packets.

Once the message is completely specified, it can be encoded into a byte sequence using the special-
ized writer function according to the message type: ER_Write_APP_MA_Request(...).

5.5. Sizing the library

The user can define several variables that will specify the size of SFM and CFM components,
thereby impacting the memory usage.

These variables are explained in detail in the HTML API documentation, in the er37_sizes.h
file. An explanation and the default value is provided for each variable.

20
Chapter 6. How to...
6.1. Use my own DES function instead of the
one provided with the library
This can be provided by redefining the ER_CALCULATE_DES and
ER_CALCULATE_DES_INVERTED macros in er_user.h to call you own function rather than
the default behaviour. This is the only header file in the library which is meant to be altered directly
by the user to tune the library's behaviour to environment-specific constraints.

21