FW Profile - C1 Implementation
FwRtConfig.c File Reference

Implements Configuration Functions of the RT Container. More...

Go to the source code of this file.

Functions

FwRtOutcome_t DummyAction (FwRtDesc_t rtDesc)
 Dummy function which always returns 1. More...
 
void FwRtReset (FwRtDesc_t rtDesc)
 Reset the RT Container descriptor (RTD). More...
 
void FwRtInit (FwRtDesc_t rtDesc)
 Initialize a RT Container. More...
 
void FwRtShutdown (FwRtDesc_t rtDesc)
 Shutdown the RT Container. More...
 
void FwRtSetPosixAttr (FwRtDesc_t rtDesc, pthread_attr_t *pThreadAttr, pthread_mutexattr_t *pMutexAttr, pthread_condattr_t *pCondAttr)
 Set the pointers to the attribute objects of the POSIX thread, mutex and condition variable used by the container. More...
 
pthread_attr_t * FwRtGetActivThreadAttr (FwRtDesc_t rtDesc)
 Get the value of the attributes of the Activation Thread. More...
 
pthread_mutexattr_t * FwRtGetMutexAttr (FwRtDesc_t rtDesc)
 Get the value of the attributes of the mutex associated to the RT Container. More...
 
pthread_condattr_t * FwRtGetCondAttr (FwRtDesc_t rtDesc)
 Get the value of the attributes of the condition variable associated to the RT Container. More...
 
void FwRtSetData (FwRtDesc_t rtDesc, void *rtData)
 Set the pointer to the RT Container data in the container descriptor. More...
 
void * FwRtGetData (FwRtDesc_t rtDesc)
 Get the pointer to the container data in the container descriptor. More...
 
void FwRtSetInitializeNotifPr (FwRtDesc_t rtDesc, FwRtAction_t initializeNotifPr)
 Define the function implementing the Initialization Action for the Notification Procedure. More...
 
void FwRtSetFinalizeNotifPr (FwRtDesc_t rtDesc, FwRtAction_t finalizeNotifPr)
 Define the function implementing the Finalization Action for the Notification Procedure. More...
 
void FwRtSetImplementNotifLogic (FwRtDesc_t rtDesc, FwRtAction_t implementNotifLogicPr)
 Define the function implementing the Notification Logic for the Notification Procedure. More...
 
void FwRtSetInitializeActivPr (FwRtDesc_t rtDesc, FwRtAction_t initializeActivPr)
 Define the function implementing the Initialization Action for the Activation Procedure. More...
 
void FwRtSetFinalizeActivPr (FwRtDesc_t rtDesc, FwRtAction_t finalizeActivPr)
 Define the function implementing the Finalization Action for the Activation Procedure. More...
 
void FwRtSetSetUpNotif (FwRtDesc_t rtDesc, FwRtAction_t setUpNotification)
 Define the function implementing the logic to set up a notification for the RT Container. More...
 
void FwRtSetImplementActivLogic (FwRtDesc_t rtDesc, FwRtAction_t implementActivLogic)
 Define the function implementing the activation logic for the RT Container. More...
 
void FwRtSetExecFuncBehaviour (FwRtDesc_t rtDesc, FwRtAction_t execFuncBehaviour)
 Define the function which executes the functional behaviour associated to the RT Container. More...
 

Detailed Description

Implements Configuration Functions of the RT Container.

Author
Vaclav Cechticky vacla.nosp@m.v.ce.nosp@m.chtic.nosp@m.ky@p.nosp@m.np-so.nosp@m.ftwa.nosp@m.re.co.nosp@m.m
Alessandro Pasetti paset.nosp@m.ti@p.nosp@m.np-so.nosp@m.ftwa.nosp@m.re.co.nosp@m.m

This file is part of the FW Profile.

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

For information on alternative licensing, please contact P&P Software GmbH.

Definition in file FwRtConfig.c.

Function Documentation

FwRtOutcome_t DummyAction ( FwRtDesc_t  rtDesc)

Dummy function which always returns 1.

This function is used as the default for the procedure actions of the RT Container.

Parameters
rtDescthe descriptor of the RT Container
Returns
this function always returns 1

Definition at line 262 of file FwRtConfig.c.

pthread_attr_t* FwRtGetActivThreadAttr ( FwRtDesc_t  rtDesc)

Get the value of the attributes of the Activation Thread.

The attribute values returned by this call are those set with FwRtSetPosixAttr or NULL if the container was initialized without calling this function.

Parameters
rtDescthe descriptor of the RT Container
Returns
the attributes of the Activation Thread

Definition at line 165 of file FwRtConfig.c.

pthread_condattr_t* FwRtGetCondAttr ( FwRtDesc_t  rtDesc)

Get the value of the attributes of the condition variable associated to the RT Container.

The attribute values returned by this call are those set with FwRtSetPosixAttr or NULL if the container was initialized without calling this function.

Parameters
rtDescthe descriptor of the RT Container
Returns
the attributes of the condition variable

Definition at line 175 of file FwRtConfig.c.

void* FwRtGetData ( FwRtDesc_t  rtDesc)

Get the pointer to the container data in the container descriptor.

This function returns the pointer which was set with the FwRtSetData function.

Parameters
rtDescthe RT Container descriptor.
Returns
the pointer to the container data.

Definition at line 185 of file FwRtConfig.c.

pthread_mutexattr_t* FwRtGetMutexAttr ( FwRtDesc_t  rtDesc)

Get the value of the attributes of the mutex associated to the RT Container.

The attribute values returned by this call are those set with FwRtSetPosixAttr or NULL if the container was initialized without calling this function.

Parameters
rtDescthe descriptor of the RT Container
Returns
the attributes of the mutex

Definition at line 170 of file FwRtConfig.c.

void FwRtInit ( FwRtDesc_t  rtDesc)

Initialize a RT Container.

The following initialization actions are performed:

  • If the container state is not rtContUninitialized, the function sets the container's state to the error state rtConfigErr and then returns.
  • If non-NULL attributes have been loaded for the container's POSIX objects (i.e. if the user has called function FwRtSetPosixAttr with non-NULL values), the attributes are initialized using their POSIX initialization functions (pthread_attr_init, pthread_mutexattr_init, and pthread_condattr_init) and then the initialized attributes are used to initialize the mutex and the condition variable.
  • If no attributes have been loaded for the container's POSIX mutex and condition variable (i.e. if the user has not called function FwRtSetPosixAttr or he has called it with NULL values for the POSIX attributes), the container POSIX mutex and condition variable are initialized with their default attribute values.
  • If any of the POSIX system calls made by this function returns an error, the container state is set to an error state (see FwRtState_t) and the error code is initialized with the error code returned by the failed POSIX system call.
  • If all the POSIX system calls made by this function are successful, the container state is set to rtContStopped.

A call to this function concludes the configuration process of the RTD. The configuration process has been successful if, after this function is called, the container is in state rtContStopped.

Parameters
rtDescthe descriptor of the RT Container.

Definition at line 52 of file FwRtConfig.c.

void FwRtReset ( FwRtDesc_t  rtDesc)

Reset the RT Container descriptor (RTD).

This function should be called at the beginning of the configuration process. The function initializes the fields of the container descriptor with default values as follows:

  • The actions of the Notification Procedure and of the Activation Procedure are set equal to a dummy action representing a situation where all procedure actions do nothing and always return 1.
  • The attribute objects for the Activation Thread, for the container mutex, and for the container condition variable are set to NULL. This represents a situation where the default values for these attributes are used.
  • The error code is set to zero.
  • The notification counter is set to zero.
  • The container state is set to: rtContUninitialized.
  • The state of the Activation and Notification Procedures is set to: STOPPED.
  • The pointer to the container data is set to NULL.
Parameters
rtDescthe descriptor of the RT Container

Definition at line 31 of file FwRtConfig.c.

void FwRtSetData ( FwRtDesc_t  rtDesc,
void *  rtData 
)

Set the pointer to the RT Container data in the container descriptor.

The container data are data which are manipulated by the container's procedures. The container descriptor holds a pointer to the procedure data. This function allows this pointer to be defined. The exact type of the container data is defined by applications for each RT Container. It is therefore unknown at the level of the RT Container module. This function accordingly treats the pointer to the procedure data as a pointer to void. In most cases, the container data will take the form of a struct whose fields represent the inputs and outputs for the procedure actions and guards.

The functions which implement the container's procedures access the container data as follows:

  • The procedure functions take the container descriptor as an argument (because they must conform to the FwRtAction_t prototype).
  • The procedure functions use the FwRtGetData function to retrieve the pointer to the container data.
  • The pointer returned by FwRtGetData is defined as a pointer to void and will normally have to be cast to its true type.

If this function is not called, the value of the container data is NULL.

This function may be called at any time but should normally be called only during the container configuration process.

Parameters
rtDescthe RT Container descriptor.
rtDatathe pointer to the container data (a value of NULL is legal if no data need be attached to the container).

Definition at line 180 of file FwRtConfig.c.

void FwRtSetExecFuncBehaviour ( FwRtDesc_t  rtDesc,
FwRtAction_t  execFuncBehaviour 
)

Define the function which executes the functional behaviour associated to the RT Container.

The argument function must conform to the FwRtAction_t prototype.

If this function is not called, the default value for the container's functional behaviour is used. This is a dummy action which corresponds to a situation where the container's functional behaviour is terminated after the first execution.

This function may only be called during the container's configuration process (i.e. before FwRtInit is called or after FwRtShutdown is called). If it is called at any other time, it causes the container's state to be put in error state rtConfigErr.

Parameters
rtDescthe RT Container descriptor.
execFuncBehaviourthe pointer to the function implementing the container's functional behaviour.

Definition at line 253 of file FwRtConfig.c.

void FwRtSetFinalizeActivPr ( FwRtDesc_t  rtDesc,
FwRtAction_t  finalizeActivPr 
)

Define the function implementing the Finalization Action for the Activation Procedure.

The argument function must conform to the FwRtAction_t prototype.

If this function is not called, the default value for the Finalization Action is used which is a dummy action which corresponds to a situation where no finalization action is performed by the Activation Procedure.

This function may only be called during the container's configuration process (i.e. before FwRtInit is called or after FwRtShutdown is called). If it is called at any other time, it causes the container's state to be put in error state rtConfigErr.

Parameters
rtDescthe RT Container descriptor.
finalizeActivPrthe pointer to the function implementing the Finalization Action for the Activation Procedure.

Definition at line 226 of file FwRtConfig.c.

void FwRtSetFinalizeNotifPr ( FwRtDesc_t  rtDesc,
FwRtAction_t  finalizeNotifPr 
)

Define the function implementing the Finalization Action for the Notification Procedure.

The argument function must conform to the FwRtAction_t prototype.

If this function is not called, the default value for the Finalization Action is used which is a dummy action which corresponds to a situation where no finalization action is performed by the Notification Procedure.

This function may only be called during the container's configuration process (i.e. before FwRtInit is called or after FwRtShutdown is called). If it is called at any other time, it causes the container's state to be put in error state rtConfigErr.

Parameters
rtDescthe RT Container descriptor.
finalizeNotifPrthe pointer to the function implementing the Finalization Action for the Notification Procedure.

Definition at line 199 of file FwRtConfig.c.

void FwRtSetImplementActivLogic ( FwRtDesc_t  rtDesc,
FwRtAction_t  implementActivLogic 
)

Define the function implementing the activation logic for the RT Container.

The argument function must conform to the FwRtAction_t prototype.

If this function is not called, the default value for the Implementation Activation Logic Function is used which is a dummy action which corresponds to a situation where the container's functional behaviour is executed at every activation cycle.

This function may only be called during the container's configuration process (i.e. before FwRtInit is called or after FwRtShutdown is called). If it is called at any other time, it causes the container's state to be put in error state rtConfigErr.

Parameters
rtDescthe RT Container descriptor.
implementActivLogicthe pointer to the function implementing the container's activation logic.

Definition at line 244 of file FwRtConfig.c.

void FwRtSetImplementNotifLogic ( FwRtDesc_t  rtDesc,
FwRtAction_t  implementNotifLogicPr 
)

Define the function implementing the Notification Logic for the Notification Procedure.

The argument function must conform to the FwRtAction_t prototype.

If this function is not called, the default value for the Notification Logic is used which is a dummy action which never skips a notification.

This function may only be called during the container's configuration process (i.e. before FwRtInit is called or after FwRtShutdown is called). If it is called at any other time, it causes the container's state to be put in error state rtConfigErr.

Parameters
rtDescthe RT Container descriptor.
implementNotifLogicPrthe pointer to the function implementing the Notification Logic for the Notification Procedure.

Definition at line 208 of file FwRtConfig.c.

void FwRtSetInitializeActivPr ( FwRtDesc_t  rtDesc,
FwRtAction_t  initializeActivPr 
)

Define the function implementing the Initialization Action for the Activation Procedure.

The argument function must conform to the FwRtAction_t prototype.

If this function is not called, the default value for the Initialization Action is used which is a dummy action which corresponds to a situation where no initialization action is performed by the Activation Procedure.

This function may only be called during the container's configuration process (i.e. before FwRtInit is called or after FwRtShutdown is called). If it is called at any other time, it causes the container's state to be put in error state rtConfigErr.

Parameters
rtDescthe RT Container descriptor.
initializeActivPrthe pointer to the function implementing the Initialization Action for the Activation Procedure.

Definition at line 217 of file FwRtConfig.c.

void FwRtSetInitializeNotifPr ( FwRtDesc_t  rtDesc,
FwRtAction_t  initializeNotifPr 
)

Define the function implementing the Initialization Action for the Notification Procedure.

The argument function must conform to the FwRtAction_t prototype.

If this function is not called, the default value for the Initialization Action is used which is a dummy action which corresponds to a situation where no initialization action is performed by the Notification Procedure.

This function may only be called during the container's configuration process (i.e. before FwRtInit is called or after FwRtShutdown is called). If it is called at any other time, it causes the container's state to be put in error state rtConfigErr.

Parameters
rtDescthe RT Container descriptor.
initializeNotifPrthe pointer to the function implementing the Initialization Action for the Notification Procedure.

Definition at line 190 of file FwRtConfig.c.

void FwRtSetPosixAttr ( FwRtDesc_t  rtDesc,
pthread_attr_t *  pThreadAttr,
pthread_mutexattr_t *  pMutexAttr,
pthread_condattr_t *  pCondAttr 
)

Set the pointers to the attribute objects of the POSIX thread, mutex and condition variable used by the container.

A RT Container uses a POSIX thread, a POSIX mutex and a POSIX condition variable. Their configuration is defined by attribute objects. This function allows the attribute objects to be loaded into the container. A value of NULL for an attribute object means that the POSIX-defined default value for that attribute will be used. The attribute objects will be initialized at the end of the container configuration process when FwRtInit is called.

The thread attributes are used when the container's thread (the Activation Thread) is started by calling FwRtStart. The mutex and condition variable attributes are used when the container mutex and its condition variable are initialized by calling FwRtInit.

If this function is not called during the container configuration process, the container will be configured with NULL values for all POSIX attribute objects (i.e. the POSIX thread, mutex and condition variable will be initialized with their POSIX-defined default attribute values).

This function may only be called during the container's configuration process (i.e. before FwRtInit is called or after FwRtShutdown is called). If it is called at any other time, it causes the container's state to be put in error state rtConfigErr.

Parameters
rtDescthe descriptor of the RT Container
pThreadAttrthe attributes of the Activation Thread (or NULL if it is desired to use default attribute for the thread)
pMutexAttrthe attributes of the container's mutex (or NULL if it is desired to use default attribute for the mutex)
pCondAttrthe attributes of the container's mutex (or NULL if it is desired to use default attribute for the condition variable)

Definition at line 151 of file FwRtConfig.c.

void FwRtSetSetUpNotif ( FwRtDesc_t  rtDesc,
FwRtAction_t  setUpNotification 
)

Define the function implementing the logic to set up a notification for the RT Container.

The argument function must conform to the FwRtAction_t prototype.

If this function is not called, the default value for the Set Up Notification Function is used which is a dummy action which corresponds to a situation where no notification set-up mechanism is implemented.

This function may only be called during the container's configuration process (i.e. before FwRtInit is called or after FwRtShutdown is called). If it is called at any other time, it causes the container's state to be put in error state rtConfigErr.

Parameters
rtDescthe RT Container descriptor.
setUpNotificationthe pointer to the function implementing the Set Up Notification logic.

Definition at line 235 of file FwRtConfig.c.

void FwRtShutdown ( FwRtDesc_t  rtDesc)

Shutdown the RT Container.

The following shutdown actions are performed:

  • If non-NULL attributes have been loaded for the container's POSIX thread, or for the container's POSIX mutex, or for the container's POSIX condition variable, the attributes are destroyed using their POSIX destruction functions (pthread_attr_destroy, pthread_mutexattr_destroy, and pthread_condattr_destroy).
  • The container POSIX mutex and POSIX condition variables are destroyed using their POSIX destructor functions (pthread_mutex_destroy and pthread_cond_destroy).
  • If all the POSIX system calls made by this function are successful, then the container state is set to rtContUninitialized to signify that the container is now uninitialized.
  • If any of the POSIX system calls made by this function returns an error, the container state is set to an error state (see FwRtState_t) and the error code is set to the error code returned by the failed POSIX system call.

After this function has been called, the container must be again configured in full before it can again be used.

This function should only be called when the RT Container is in state STOPPED and after its Activation Thread has terminated execution. Enforcement of this constraint is under the responsibility of the user.

Parameters
rtDescthe descriptor of the RT Container.

Definition at line 105 of file FwRtConfig.c.

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