FW Profile - C1 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.
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 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.
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.
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
.
Two forms of error checks are performed by the RT Container functions:
FwRtState_t
).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.
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.
The basic usage of a RT Container within an application is as follows:
FwRtConfig.h
.FwRtStart
.FwRtNotify
.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
.