FW Profile - C1 Implementation
RT Container Implementation

RT Containers are one of the three modelling concepts offered by the FW Profile.

State Machines and Procedures allow the functional aspects of a software application to be modelled. RT Containers complement them by offering the means to capture the time-related behaviour of an application. The acronym "RT" stands for "Real-Time".

RT Containers provide a way to encapsulate the activation logic for a functional behaviour. A RT Container can be seen as a representation of a thread which controls the execution of some functional behaviour. The RT Container allows the conditions under which the thread is released to be specified.

The C1 Implementation represents a RT Container through a RT Container Descriptor (RTD). An RTD is a data structure which holds all the information required to describe a RT Container. It is defined as an instance of type struct FwRtDesc. Users normally only manipulate pointers to RTD which are defined as instances of type FwRtDesc_t. The internal structure of an RTD is described in FwRtConstants.h. Most applications are not concerned with the internal structure of an RTD and can ignore this header file.

Applications manipulate a RT Container by passing its RTD to the functions defined by the C1 Implementation. Thus, for instance, an application sends a notification to a RT Container through the following function call: FwRtNotify(rtDesc). Here, rtDesc is the pointer to the RTD of the RT Container to be notified.

RT Container Modules

The implementation of the RT Container concept consists of several modules as described in the table:

Module Description Files
Core Provides an interface to start, stop, and notify a RT Container. FwRtCore.h, FwRtCore.c
Config Provides an interface to configure a newly created RTD and shut it down after use. FwRtConfig.h, FwRtConfig.c

RT Container Attributes and Behaviours

RT Containers are built upon POSIX threads. A RT Container encapsulates one POSIX thread, one POSIX mutex and one POSIX condition variable. By default, the RT Container is instantiated with POSIX-defined default values for all the attributes of its POSIX objects. If these default values are not adequate, they can be changed with functions offered by the the configuration interface in FwRtConfig.h.

The RT Container must be configured with its functional behaviour. Functional behaviour is encapsulated in functions which must be implemented by the user and which, at configuration time, are passed to the container as function pointers.

RT Container Data

The RTD includes a field holding a pointer to the Container Data. The Container Data are data which are manipulated by the functional behaviour attached to the container. The exact type of the Container Data is defined by applications for each RT Container. In most cases, it will take the form a struct whose fields represent the inputs and outputs for the container actions. The RTD treats the pointer to the Container Data as a pointer to void. Functions FwRtSetData and FwRtGetData allow this pointer to be set in, and to be retrieved from, an RTD.

RT Container States

A RT Container has a state which can be accessed with function FwRtGetContState. Three nominal states are defined for a RT Container:

  • rtContUninitialized: this is the state of the container when it is being configured, i.e. before it is initialized for the first time with function FwRtInit or after it has been shut down with function FwRtShutdown.
  • rtContStopped: this is the state of the container after it has successfully completed its configuration and after it has been stopped with function FwRtStop.
  • rtContStarted: this is the state of the container after it has been successfully started with function FwRtStart and before it is stopped with function FwRtStop.

Additionally, the container may be in a number of error states as described in the next section. The range of container states is defined by type FwRtState_t.

Error Checking

Two forms of error checks are performed by the RT Container functions:

  • It is checked that POSIX system calls are successful. A POSIX system call fails if it returns an error code. In that case, the error code is stored in the error code field of the RTD and the state of the RT Container is set to an error state which depends on the system call which reported the error (see list of RT Container states in FwRtState_t).
  • It is checked that configuration functions are not called on the container during its normal operation (i.e. after the container has been initialized with FwRtInit and before it is shut down with FwRtShutdown). If a configuration function is called during normal operation, the state of the RT Container is set to the error state rtConfigErr.

The container state can be access with FwRtGetContState. If the RT Container is in an error state, its behaviour is undefined.

Thread Safety

The RT Container components of the C1 Implementation define data which may be accessed either by the container's internal thread (the Activation Thread) or by an external user thread (the thread responsible for making notification requests). The functions to start, stop and notify a thread use the container's mutex to guarantee access in mutual exclusion and are therefore thread-safe. All other container functions (e.g. the configuration functions) are not intended for use during the real-time operation of the container and are not thread-safe. It is the responsibility of the user to ensure that they are called in mutual exclusion.

Basic Usage

The basic usage of a RT Container within an application is as follows:

  1. The RT Container is configured through the functions offered by FwRtConfig.h.
  2. The RT Container is started with function FwRtStart.
  3. The RT Container is sent one or more notifications by calling function FwRtNotify.
  4. The RT Container is stopped with function FwRtStop.

After the container has been stopped and after its activation thread has terminated execution, it can be re-started. Function FwRtWaitForTermination can be used to wait for the termination of the Activation Thread. When the container is no longer needed, it should be shut down with function FwRtShutdown.

Examples of creation and configuration of RT Containers can be found in module FwRtMakeTest.h. Examples of operation of a RT Container can be found in module FwRtTestCases.h.

P&P Software GmbH, Copyright 2011, All Rights Reserved