Introduction

Scope

In this application note you will learn about what types of supervision modes are supported in the watchdog stack of RTA-BSW and how to configure each of these modes.

Definitions and Abbreviations

Wdg/WDG: Watchdog

WdgIf: Watchdog Interface

WdgM: Watchdog Manager

SE: Supervised Entity

BSW: AUTOSAR Basic Software, Hardware independent service layer

RTE: AUTOSAR Run-Time Environment

OS: AUTOSAR Operating System

Confgen: BSW Configuration Generation

API: Application Programming Interface

RE: Runnable Entity

PPort: Provider Port

RPort: Requiring Port

CPT: Component

OIE: Operation Invoked Event

SW / SWC: Software / Software Component

Toolchain

It is assumed you are using the RTA-CAR 9.2.1 toolchain:

It is also expected you are using RTA-OS VRTA port on version 3.0.46. Other versions may be similar but not the same.

For the workflow section of this guide it will be assumed you are working on the latest version of the standard VRTA starterkit: RTA-SK_VRTA_GCC_Standard_9.2.1_R1.

Prerequisites

It is assumed that the reader has good knowledge of AUTOSAR Methodology and Architecture.

It is assumed you are following the workflow by building on the latest version of the standard VRTA starterkit: RTA-SK_VRTA_GCC_Standard_9.2.1_R1.

Watchdog Supervision Explained

Each entity that a Watchdog is supervising is called a Supervised Entity (SE). There may be zero, one or many such supervised entities per a single software component or BSW service component. In this way a Supervised Entity can be a definition of how single piece of software, group of functions or individual function is supervised; so long as there is a collection of checkpoints that is called from within this piece of software. This collection of checkpoints is called a graph where at least one of the checkpoints should be the initial checkpoint and there should be a description of what the proper transitions between each checkpoint should be in the configuration for the supervised entity.

When the supervised entity runs if it makes the correct sequence of calls to the checkpoints in the way that was described in the configuration of the WdgM (Watchdog Manager) then the running of the software will continue as normal. However, if supervision is started (i.e. an initial checkpoint is called for a particular SE) and then for whatever reason, at least one checkpoint is not 'correctly reached' in that graph, then the state of the Wdg will be changed accordingly and report that that the supervision has failed.

The method for defining what is the "correct" way to reach each checkpoint is defined by the type of supervision used. Any supervised entity may be monitored by one or multiple types of supervision using the same set of checkpoints (A description of how this is possible will be expanded upon later).

There are 3 different types of supervision that can be used to supervise an entity:

• Alive Supervision
• Deadline Supervision
• Logical Supervision

Logical Supervision

Logical supervision is the most simple type of supervision. Through configuring a series of checkpoints and the transitions between them you can describe a control flow of the checkpoints that must be reached and in what order. So long as the checkpoints are not reached in an incorrect order the watchdog is satisfied and there will be no Wdg reset. If the checkpoints are reached in an incorrect order then the wdg will change the state of the local supervision state machine (see the later section of this guide on this).

Example

Say you had a runnable entity which called a function you wanted to supervise named 'MySupervisedFunction' with the program flow such as this:

You could put in calls to reach checkpoints such as this to check that the program flow is operating at is should:

The result of this is that you should also create a graph of these checkpoints to reflect this in the WdgM Module (as described later in this application note). A graph representing this would end up looking something like this:

With a set of internal transitions like this:

External Graphs and External Logical Supervision

It is possible to configure a transition from the final checkpoint of one graph to the inital checkpoint of another one. In this manner you are explicitly stating a transition from the end of one SE to the start of the next SE, this is called an 'external transition' and the combination of the SEs and external transitions is called an 'external graph'. From the WdgM specification:

Deadline Supervision

Deadline supervision can be used to monitor the running of supervised entities which functionality appears to be more asynchronous or 'fire and forget'. You can configure deadlines for the amount of time it should take to reach each checkpoint in the graph, this works by setting a minimum and maximum time that should pass between a pair of checkpoints executing.

See the definition of 'Deadline Supervision' from the AUTOSAR specification below:

Because deadline supervision describes the amount of time it takes to transition between 2 checkpoints it is reasonable to state that there is always a small amount of logical supervision implicit in the use of deadline supervision. An alternative way of looking at it could be that deadline supervision is simply an extension of logical supervision with the added constraint of a time limit for any single step or multi-step transition.

Example

Say you had some runnable that asynchronously called an API that you wanted to supervise how long it takes to call with program flow such as:

You may want to supervise the function to test that it takes its expected 600ms target, give or take a reasonable amount of time:

For example if "API_that_takes_200ms" usually takes 200ms but never takes less than 100ms and never longer than 300ms and "API_that_takes_400ms" never takes less time than 200ms and never longer than 600ms you can reasonable set a lower and upper bound on how long the runnable should be running: the function should take longer than 300 ms and less than 900ms.

More importantly you can define with certainty that if it takes less time than 300ms or longer than 900ms, you know there is a failure in the running of the ECU and the Wdg needs to take action to correct the running of the ECU. See the example configuration below:

An example a timeline, beginning from reaching start checkpoint until reaching the end checkpoint, where the Wdg will consider the running time to be acceptable:

An example a timeline, beginning from reaching start checkpoint until reaching the end checkpoint, where the Wdg will consider the running time to be unacceptable, because it reached the end checkpoint too soon:

An example a timeline, beginning from reaching start checkpoint until reaching the end checkpoint, where the Wdg will consider the running time to be unacceptable, because it reached the end checkpoint too late:

Alive Supervision

Alive supervision can be used to check if a task that executes periodically activates an acceptable number of times. You can configure the WdgM to check for this by setting a lower and upper bound for how many times each checkpoint in the graph is reached.

See the definition of 'Alive Supervision' from the AUTOSAR specification below:

Note that because the alive supervision method only considers the frequency of reaching each check point, the actual transitions between each checkpoint is entirely unimportant to alive supervision.

Example

Say you had some runnable that periodically calls an API and you wanted to supervise it to make sure it definitely calls it in the right interval:

You could add one checkpoint to the start of the periodic function like this:

If your periodic function ran at a cycle time of 10ms (0.01s) and the WdgMSupervisionCycle had a cycle time of 3ms, then you may expect 3 occurrences of your periodic function in 10 supervision cycles (give or take one to allow for some error).
You could create an configuration for this such as this example below:

Wdg States

Through the supervision of SEs, the Wdg will change its internal state machines states to reflect the outcome of the supervision and determine when the Wdg will initiate resets.

The outcomes of supervision of an SE effects the local state machines, the states of the local state machines effect the global state machines.

Local Wdg States

For every supervised entity there is a local state machine with a set of 4 local Wdg states:

The sate machine for the transitions between these sates is described below.

 For more information on the transitions of this state machine see chapter "7.1.3 Local Supervision Status" of the AUTOSAR Specification of Watchdog Manager.

Global Wdg States

Based on the Local Supervision Status of all Supervised Entities, the Global Supervision Status is computed. There is one state machine which shared by the whole Wdg instance with 5 states and operates in a similar manner to the local state machine with a couple of additions:

The sate machine for the transitions between these sates is described below.

 For more information on the transitions of this state machine see chapter "7.1.3 Global Supervision Status" of the AUTOSAR Specification of Watchdog Manager.

WdgM Modes

In your configurations you may wish for a SE to be supervised differently at different times. A classic example of this is that you may wish for the supervision parameters to be less strict when the ECU is starting up and be more strict when it is running normally, so you could have a 'slow' mode and a 'fast' mode. The way you would configure this is configure something called a WdgM Mode which will be a container for all the rules that you wish to use at one particular time. For each different way you wish for a SE to be supervised you need a different mode containing all the rules that will be used while that mode is active.

The rules that can be changed by changing the WdgM Mode are:

• Alive supervision parameters
• Deadline supervision parameters
• External logical supervision parameters

Configuration Workflow

Summary

1. Create Wdg, WdgIf, WdgM modules
2. Generate BSW
3. Add interfaces & ports to SWC which will interface with WdgM
4. Regenerate Component Code Frame
5. Define & implement your supervised entities

Create Wdg, WdgIf, WdgM modules

Create a new BSW modules for Wdg, WdgIf and WdgM as shown below:

Wdg Module

Configure the Wdg module to look something like this:

WdgIf Module

Configure the WdgIf module to look something like this:

The parameter WdgIfDevice should point to the device configured in the Wdg Driver. In the example given this is WdgGeneral_0.

WdgM Module

Configure the WdgM module to look something like this, after which, you will make a supervised entity and a mode:

The parameter WdgMWatchdog should point to the device configured in the WdgIF module. In the example given this is WdgIfDevice.

Configuring SEs & Logical Supervision

Create your supervised entity and decide on the checkpoints that you will need to be in the supervised entity, for example here we have 2 checkpoints "StartCheckpoint" and "EndCheckpoint" which will be used for deadline supervision, but you may need different for your own SE:

You must also configure the internal transitions; this will define the logical supervision of the SE. Here in this example you will only need one transition, from the start to the end checkpoint:

For a larger example of how to configure logical supervision see the earlier chapter "Watchdog Supervision Explained: Logical Supervision: Example"

Configuring Your Mode & Other Supervisions

You must now configure at least one mode (e.g. "WdgMode_0" in the example above) and set this mode to be your initial mode:

You must also configure the supervision cycle time of the mode and the number of acceptable expired supervision cycles allowed for the mode. This will be important to configure a sensible alive supervision configuration.

Inside the mode you may create rules for Alive supervision, Deadline Supervision or External Logical Supervision (See earlier chapters of this guide to understand the purpose of these rules).

Configuring Alive Supervision

To configure your alive supervision you can configure the following

• The 'normal' expected times the checkpoint will be reached in "WdgMExpectedAliveIndications"
• The maximum number of additional unexpected alive indications in "WdgMMaxMargin"
• The maximum number of expected alive indications allowed to fail to be indicated in "WdgMMinMargin"
• The number of supervision cycles, in which you expect the 'normal' about of alive indications, in "WdgMSupervisionReferenceCycle"
• The checkpoint, which when reached will trigger an alive indication for this supervision, in "WdgMAliveSupervisionCheckpointRef"

An example configuration is below:

Configuring Deadline Supervision

To configure your deadline supervision you can configure the following

• The minimum time the task will take in "WdgMDeadlineMin"
• The maximum time the task will take in "WdgMDeadlineMax"
• The initial checkpoint that the deadline supervision will start at in "WdgMDeadlineStartRef"
• The second checkpoint that the deadline supervision will end at in "WdgMDeadlineStopRef"

An example configuration is below:

Generate BSW

Once you have created your BSW configuration you must enable / select the modules to be generated in the BSW code generation step, then re-generate the BSW:

On top of generating the BSW code, this will also generate the WdgM component which you will use for the next step in your workflow:

Add Ports to SWC Which Will Interface With WdgM

When you generated the WdgM component along with the BSW, it also generated some necessary interfaces. For example, there are some Client Server Interfaces created for the WdgM component such as the 'WdgM_LocalSupervision' interface:

On the side of the WdgM component this interface creates a PPort (Provide Port) which acts a virtual server location where clients (other SWCs) can trigger a call to this server over the RTE's virtual bus saying that a particular checkpoint has been reached.

The server side of this communication has been created for us, so now we will reuse this interface to create some RPorts (Require Ports) client ports from which our SWCs will have access to make these calls.

Create PPorts

Open the 'MasterSWC' in the 'SWC Editor' and create 2 RPorts using the client server interface 'WdgM_LocalSupervision' (Repeat the following step twice to create 2 RPorts):

Call the ports "RPort_StartCheckpoint" and "RPort_EndCheckpoint" .

Create Server Call Points

Go to the 'Functions' tab and then the 'Server Call Points' tab and choose the runnable RE_RunTest:

Once RE_RunTest is selected create your server call points for both of the RPorts you just created:

Connect Ports

Now we need to connect the ports on the WdgM component to the MasterSWC in our composition - we already have both these Components imported to the TopLevelComposition, so all we need to do here is connect the ports.

Open the TopLevelComposition and navigate to the ManualConnectionEditor:

Select the WdgM as the 'Source Component' and the MasterSWC as the 'Destination Component' and map the source PPort "...StartCheckpoint" to the destination RPort "...StartCheckpoint" and then do the same for the End checkpoints:

The result should look something like this with 2 new port connections created from WdgM to the MasterSWC (note that the global mode connection already existed in our starterkit, but you would create a connection for that in a very similar manner).

In the composition overview it will look like this:

Now you should regenerate the ECU extract:

Map Runnable Entity to Task

We need to map the functions that will handle the CheckpointReached functions to an OS task so that they know when to be run and what task is responsible for doing this.

Open the "EcucValueCollection", navigate to the "Entity to Mapping Editor" and search for the checkpoint runnable entities that will have been created:

Drag the two newly created runnables to the OsTask_BSW:

(They do not need to be this high of a priority in reality)

Re-run BSW Configuration Generation

Now we have updated our top level composition you must update the ECU FlatView SWCD file (ApplicationECU_FlatView_SWCD.arxml). The easiest way to do this is to re-run confgen.

This should create the following assembly SW connectors:

Re-generate RTE

Save the project and re-generate the RTE.

This will create the functionality in the RTE we have been creating a configuration for.

For example in the file RTE_MasterSWC.h file

Regenerate Component Code Frame

To get an example of how to use the asynchronous call to the checkpoints you can re-generate the component code frame for the MasterSWC:

You should see in the generated file, inside the runnable entity that the event was mapped to, you should see some asynchronous calls to the checkpoint reached functions generated for you.

Define & implement your supervised entities

The final step is to create the code for the supervised entity, and add the calls to the checkpoints in that function.

For example:

Generate the MCAL

You must now generate the MCAL for your configuration of the Wdg.

For the VRTA target this is done by running the script 01_mcal.bat which will call the VRTA McalGen for you:

This may involve more steps for other hardware targets.

Build

Now build your ECU using your build system.

For the VRTA target this is done by running the script 02_build.bat.