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 important properties. It does:

• • •

Explain the properties that are relevant for a developer who considers using the library: its relationship 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 implementation, 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 described 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 library function, and furthermore, it does not perform explicit calls to a timing function, nor to hardware 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 providing two completely independent modules: the SFM (Safe Functional Module) and CFM (Communication Functional Module). These modules support completely asynchronous communication, 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 connections Notify the library often enough to allow time-related functions (timeouts, etc.) to perform appropriately. Please note that this implies that the current time must be provided by the user as parameter 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 hardware and supporting computing platform, and provide the raw data to the library. For more details 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 communications used as physical transport for Euroradio communications.

3

The basic concepts

The CFM (Communication Functional Module), that implements the following protocol layers: • • • • 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 representation of meaningful data out of such sequences of bytes. The FFFIScom library supports these two independent units without any coupling: application programmers 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 application 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 sublayers 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 application-level data structure and turning them into sequences of bytes according to the standard, and decoding, 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 entire 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 variables.

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 configuration structures can be changed, discarded if stored as a local variable, etc. without altering the subsequent 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 example, an EVC connected to a single RBC needs one Network. This network can support one physical 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 network 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 (ER37_Modem_Event_Data_To_Modem) the DCE from the library

• • •

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 Section 5.5, “Sizing the library” for more information about library sizing issues.

3.7. Application layer messages encoding/decoding
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 declares a structure. Typical application message encoding/decoding is explained the section Section 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 increasing 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 communication, 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 facilities 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 end7

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 corrupted an safe processing is not guaranteed anymore. If the computed and stored CRCs are equal, the following steps are performed: 1. 2. 3. The protection is removed y invalidating the ending signature (ending signature is bitwise negated). The specific code of the called function is performd. 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 different qualities and different impact on performances.

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

The first level ensures that objects passed to the library have been properly initialized. The computational 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 subset026 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 basically 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. 2. 3. The Trace function The failed assertion function 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 extended 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 library 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 application. 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(...); /* } else { /* /* /* } } here comes the application */

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 performed 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. 2. Optional features options : Assertions, Protection Level, DES provider. 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 indicated 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 #define #define #define #define #define #define #define #endif And compile the sources: gcc -DER_ENABLE_USER_INCLUDE -I. *.c ER_ENABLE_MINIMAL_OBJECT_PROTECTION ER_ENABLE_TRACES ER_USE_LIBRARY_DES ER37_MAX_SAFETY_NETWORKS 2UL ER37_MAX_SAFETY_CONNECTIONS 10UL ER37_MAX_SAFETY_MESSAGES 2UL ER37_MAX_SAFETY_MESSAGES_HP 2UL ER37_IMC_MAX_FIFO_SIZE 5UL

4.3.1. Protection Level
One, and exactly one of the following must be defined: 1. 2. 3. ER_MINIMAL_OBJECT_PROTECTION ER_STANDARD_OBJECT_PROTECTION ER_EXTENDED_OBJECT_PROTECTION

4.3.2. Traces
One, and exactly one, of the following must be defined: 1. 2. ER_ENABLE_TRACES 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. 2. ER_USE_LIBRARY_DES 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 gracefully 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 following 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 procedure 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. 2. Library status monitoring IMC communication

14

Typical usage

3. 4. 5.

Network and Safety connections management Sending and receiving Application messages 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 network or different library version) An error in the CFM propagated in the SFM through the ICM the function example_get_library_status in

See for a practical example 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 messages targeted to the CFM using ER37_SFM_Get_IMC_Message. See for a practical example the functions example_imc_to_tcpip ample_tcpip_to_imc in er37_example_fsm.c. and ex-

5.1.2.3. Network and Safety connections management
Network and Safety connections lifecyle involves several tasks: connection establishment, connection 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 initialize and connect a Network. As network initialization and connection impacts the CFM, these operations are asynchronous. They involve the following sequence of operations: 1. 2. 3. Network initialization using ER37_SFM_Initialize_Network. Network initialization monitoring using ER37_SFM_Get_Network_Status If the SFM is the connection initiator (I.e. the party which calls the other party), Network connection 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 us15

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 association with that network, using the following operations: 1. 2. 3. Connection initialization using ER37_SFM_Initialize_Connection. Connection initialization monitoring using ER37_SFM_Get_Connection_Status If the SFM is the connection initiator (I.e. the party which calls the other party), Connection establishment using ER37_SFM_Connect_Connection. Connection establishment can only be performed after successful connection initialization. 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.

4.

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 connection: • • 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 conditions 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 ER37_SFM_Get_Safety_Connection_Status. be monitored using the function

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. 2. 3. The ER37_SFM_Disconnect_Safety_Connection function has been invoked. The peer Safety connection has requested disconnection 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 ER37_SFM_Disconnect_Safety_Connection call. the connection, he can issue a

This call orders the safety connection to disconnect at the next ER37_SFM_Process call. It is important 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 connection 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 receiving services. It can use the Subset-026 application codecs provided with the library (See Section 5.4, “Using the application layer codecs”for a complete explanation), or decide to send any other 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 following 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 procedure 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 procedure 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 incoming 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 qualityassurance 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 enumeration.

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 contains 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 contained in the message. NOTE: in the UNISIG Subset-026 specifications, a distinction is made between messages and packets, 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 structure, 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 specify the included packets. Once the message is completely specified, it can be encoded into a byte sequence using the specialized 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