pnp-software/fwprofile

C Implementation of UML State Machines and Activity Diagrams for Safety-Critical, Real-Time and Embedded Applications.

FW Profile

C Implementation of an unambiguous definition of State Machines and Activity Diagrams for Safety-Critical, Real-Time and Embedded Applications. See the definition of the profile and the user manual of its C implementation.

Its main features are:

• Well-Defined Semantics: clearly and unambiguously defined behaviour.
• Minimal Memory Requirements: core module footprint of a few kBytes.
• Small CPU Demands: one single level of indirection (due to actions and guards being implemented as function pointers).
• Excellent Scalability: memory footprint and CPU demands are independent of number and size of state machine and procedure instances.
• High Reliability: test suite with 100% code, branch, and condition coverage (excluding error branches for system calls).
• Formal Specification: user requirements formally specify the implementation.
• Requirement Traceability: all requirements are individually traced to their implementation and to verification evidence.
• Documented Code: doxygen documentation for all the source code.
• Demo Application: complete application demonstrating capabilities and mode of use.
• Support for Extensibility: an inheritance-like mechanism is provided through which a derived state machine or a derived procedure is created from a base state machine or base procedure by overriding some of its actions or guards.
• Processor Architecture Independence: independent of processor architecture, suitable for 8, 16, 32, 64-bit systems.
• Simple programming interface: allowing fast manual definition of state machines or activity diagrams directly at the C code level, or development of a code generator for a UML modeling tool.

Web-Based Modeling Tool and Code Generator

The FW Profile Editor is available as a web-based tool to help design FW Profile state machines and procedures and to automate the generation of the C-code which configures them. The tool can be accessed from here.

The FW Profile Editor is also available for local installations at customer sites. It can be downloaded on a free and open licence from here.

Examples

A collection of examples is published by GitBook, get the online access here.

Frequently Asked Questions

A list of FAQs is available here.

Ownership

The owner of the project is P&P Software GmbH.

License

Free use of this software is granted under the terms of the Mozilla Public Licence v2 see LICENSE.

fwprofile's Issues

Probable Error in Release Script

I tried running the Release script from a directory other than the /fwprofile directory and I get a number of error messages. I did not investigate the matter in detail but I have the impression that the script expects the Makefile to be present in the directory from which it is run.

For the record, the command I used is:

~/Projects/fwprofile/Release.sh 1.3.1 /home/ap/Projects/fwprofile-examples /home/ap/Projects/fwprofile

PS: a constraint that the Release script can only be run from the /fwprofile directory is for me acceptable.

Type of index variables

I saw that all index variables (e.g. to access action array, nodes, etc) are of type "signed char", so are in the range 0..127. What is the reason for this limitation ? For a big procedure or state machine you would run into problems...
Also, I think it would be much better to use normal "unsigned int" for index variables as the generated code runs much faster (unless you have an 8-bit processor) and requires less code (no masking on variable access).

Potential Memory Leak

The static analysis performed by ESA has shown the following potential memory leaks: in FwPrCreateDer, there are two malloc calls; if the first one succeeds but the second one fails, then there will be a memory leak.

This finding is correct but, if there is a malloc failure in this or any other functions in module FwPrDCreate then the function where the failure occurred returns NULL and the user should simply stop operation because nothing will work. We regard it as the user's task to handle the memory leak (but, really, what needs to be handled is the failure of the malloc operation).

We are therefore not going to change the code but we will add a comment to the doxygen documentation so that users are aware of the issue.

Value of Error Code in FAQ

This issue was first raised as Mantis 297.

The text in the FAQ refers to "success" as the value of the error code in the absence of any errors. In fact, the value is either "smSuccess" or "prSuccess".

Guards of decision nodes correctly evaluated ?

I am not totally sure if this is a bug, but I cannot explain the behaviour otherwise.

• I used the provided Example 3 project and downloaded the code to build an executable. I therefore had to provide an implementation for Guard1 and Guard2 of the decision node.
• In Guard1 I return false (0) and Guard2 I return true (1). When running the procedure, I assumed that "Node 4: Action 2" will be executed.
• However, it is not. Instead, Guard1 is always evaluated over and over again. This is wrong, isn't it ?

I had a quick look at the code, but find it difficult to understand. However, line 81 in FwPrCore.c seems a bit odd as the comment for the loop indicates "Execute loop until guard ... is true" while the (pseudo-) code is "while (trueGuardFound == true) {"...

Comment about Dead Code in CrFwAux

Feedback from ESA after execution of static code analysis.

Dead code has been found in module CrFwAux. The finding is correct but this module implements a generic consistency check for the framework data structures. Since the check is generic, it may contain dead code for some specific instantiation of the framework. Also, as explained in its docygen documentation, this module is not intended to be included in the final application executable.

To facilitate future runs of the static code analyzer, we will add a comment in the source code of the following kind: // The following can be dead code, depending on the specific instantiation of the FW Profile.

Execution Constraints for State Machines

This issue was first raised as Mantis Issue 307.

The FW Profile Definition Document currently informally defines a number of "execution constraints" for state machines (such as the "nesting rule"). It would be preferable if the definition were made more formal (as was already done for the constraints C1 to C8 and D1 to D3).

SM Configuration When Too Many Out-Going Transitions

I had one case (the InCmd component of the CORDET FW) where the declaration of one state had too many out-going transitions but this error was not caught by the configuration check. I need to verify whether this point to a gap in the configuration check.

Embedded State Machines and State Machine Extension

The rules for embedded state machines and state machine extension are not very clear in the FW Profile Definition Document and need to be clarified. I propose to do it as described below.

Let S be a state of state machine SM_A and let SM_B be a state machine derived from SM_A. The rules for adding embedded state machines to SM_B are as follows:

• If state S is "empty" in SM_A (i.e. it does not have any embedded state machine), then it is allowed to add any embedded state machine in state S of SM_B
• If state machine SM_E is embedded in state S in SM_A, then, in state S of SM_B, it is allowed to replace SM_E with a state machine derived from SM_E

The basic idea is that, during the state machine extension process, you are allowed either to add new embedded state machine or to replace existing embedded state machines with their children (i..e when you extend a state machine, you can also extend its embedded state machines - see figure below).

smembeddingandderivation

NB: Marcel points out to me that the current implementation of the FW Profile does not allow an embedded state machine in a base state machine to be overridden.

NB#2 This issue was initially and mistakenly submitted in the cordetfw project.

Double Execution of Procedure Guard

With certain node topologies, it may happen that, as part of the same execution of a procedure, the same guard is evaluated twice. This should not have any consequence because guards are required to be free of side-effects but it might be inefficient and it makes the validation of the behaviour shown in figure 4 of the FW Profile Definition Document harder. For these reasons, I should consider changing the implementation of function FwPrExecute in module FwPrCore to avoid the double call and to be easier to map to the behaviour of figure 4.

Typos and Editorials

This ticket was initially raised as Mantis Issue 759:

• In section 4.5 of the FW Profile Definition document: "exaple" --> "Example"
• In section 4.2 of the FW Profile Definition document: in constraint C7, use "transition trigger" instead of "transition command" for consistency with terminology used in constraint C5.
• In table 4, "Notification" is mis-spelt twice.
• In section 5.1 of the FW Profile User Manual: "an application notifies
  a RT Container through the following function call: FwRtExecute(rtDesc)" --> an application notifies a RT Container through the following function call: FwRtNotify(rtDesc)".
• In the FW Profile Definition Document, change: PP-DF-COR-00001 to: PP-DF-COR-0001

Order of Operations in Transition Execution

Figure 8 of the FW Profile Definition Document defines the behaviour to perform a transition in a state machine. According to the figure, when the transition is a state, then the Current State is updated and then its execution counter is reset. The implementation of this logic in function ExecTrans in module FwSmCore performs these two operations in the opposite order. As far as I can tell, this has no impact on the externally visible behaviour of a state machine but, for consistency with the design, the order of the two operations should be inverted.

Wrong Format Specifier

This is a finding from the ESA static analysis:

In FwSmAux.c, lines 81 and 82 specify a ‘%d’ when in fact their arguments are unsigned integers – so in principle they should be using the ‘%u’ specifier.

Error in Doxygen Comment of Function FwPrGetCurNode

The doxygen comment for the FwPrGetCurNode function includes the following statement: "If the procedure is in the STARTED state but has not yet executed the any action (because the guard from the initial node is still false), this function returns -1". This should be changed to: "If the procedure is in the STARTED state but has not yet executed the any action (either because it has not yet been executed or because it has been executed but the guard from the initial node is false), this function returns -1".

Running Valgrind on Tutorials

I think that there is a minor inconsistency in the Release script for the FW Profile. At one point, the comment states: "Run the Demo Application and tutorials with Valgrind". However, Valgrind is only run on the demo application. Later in the script, where the headers are added to the test reports, the following commands are attempted:

sed -i -e "1i${H_L1}${H_ML6}${H_DATE}${H_CP}${H_VER}${H_L1}" ${OUT_LOG}/PR_Example1_Valgrind_Report.txt sed -i -e "1i${H_L1}${H_ML6}${H_DATE}${H_CP}${H_VER}${H_L1}" ${OUT_LOG}/RT_Example1_Valgrind_Report.txt sed -i -e "1i${H_L1}${H_ML3}${H_DATE}${H_CP}${H_VER}${H_L1}" ${OUT_LOG}/SM_Example1_Valgrind_Report.txt sed -i -e "1i${H_L1}${H_ML4}${H_DATE}${H_CP}${H_VER}${H_L1}" ${OUT_LOG}/SM_Example2_Valgrind_Report.txt sed -i -e "1i${H_L1}${H_ML5}${H_DATE}${H_CP}${H_VER}${H_L1}" ${OUT_LOG}/SM_Example3_Valgrind_Report.txt

These commands actually fail because the test reports do not exist. I assume that the intention was that these commands be commented out. If this is, please update the release script accordingly.

Some problems with the online editor

first i hope this is the right place for problems with the editor

I'm working with STM32 microcontrollers and the SW4STM32 IDE with STMCubeMX for configuration of the devices.

the onlineEditor is great i've only to download the zip, extract it in the right place ..
then i have to edit some files.
I created a FSMnameMain.h
in FSMnameMain.c i delete the main() function
in stm32 main.c i include FSMnameMain.h so the functions are available
... ???
An option bottom With or without main() would be nice

so my first real issue is the limitation of the global variable definitions
int and uint ...

this results in static unsigned int and these are located in FSMname.c
so they are NOT global with respect to the main() function is in FSMnameMain.c

uint32_t uint_16_t ... are standard with STM32 microcontrollers

so there is no such global variable xy available.

why is there no ** extern uint ,,,** in the FSMname.c and the global variable in FSMnameMain.c

in some cases in special programming microcontrollers we need to use volatile for some vars i.e for IRQ handling and some parts of code, where the compiler shouldn't optimise out peace's of code.

So i think it makes sense when the user is able to edit REALLY globals in FSMnameMain.c
and NOT semiglobals in the FSMname.c file
This is also the case for the so called global #include "file.h"

And the limitation of only 8 semi global variables is definitive the killer for bigger StateMachines

New Property on Notification Processing

In view of the fact that the "Stop RT Container" operation also increments the notification counter, We need a new property which states that the number of times the Activation Procedure has been executed is the same as the number of times the container has been externally notified.

Keeping Track of Previous State in State Machines

One feedback from the CHEOPS Project is that it would often be useful to keep track of the previous state of a state machine. This would require extending the size of the State Machine Descriptor and would add a small overhead to execution of a state transition but allow, for instance, a transition action or a state entry action to query the descriptor for the source state of a transition.

Decrement of Notification Counter in Activation Thread

At present, the activation thread decrements the notification counter immediately after having detected it to be greater than zero and just before executing the Activation Procedure. It might make sense to move the decrement after the Activation Procedure. This would have the advantage that, in the "normal" case where notification are processed one at a time, the notification counter remains different from zero for as long as the Activation Procedure has not finished running. Users can therefore check the value of the Notification Counter if they wish to know whether the processing of the notification is still under way.

fw profile repository is detected as the wrong language

The header files are detected as C++ instead of C. It's just a cosmetic issue, but it can lead to misleading for the users. Here is the proposed solution: https://github.com/github/linguist#overrides

Add step-by-step procedure for creating a release

Tests and examples not built / run by Travis

The fwprofile source code is automatically built and linked to a library every time the master branch advances by Travis CI. However, the examples and tests which are actually included are neither built nor run.

1. update Makefile to include build instructions also for the examples and tests,
2. update .travis.yml to build examples and build / run the tests