Out of Step (Z) Variables
The normal order of variable use in a task is for it to be set and then read. Out of Step (Z) Variables identifies global and static variables whose calculation order is read-then-set. In task-based software, this can cause stale values for a variable to be used in calculations.
Consider the following code. The variable globalA is initialized, and thus, even the first time taskA is invoked, it finds a value for globalA. However, taskA updates the value of globalA before completing. The next time taskA is invoked, the value it reads for globalA is that which existed at the end of the last invocation. This might be the desired behavior, but it could also be an indication of a programming error, where globalA should first be assigned (e.g. by reading a sensor).
int globalA = 1;
int subX() {
int localX;
localX = globalA;
return localX;
}
void subY(int paramY) {
globalA = paramY;
}
void taskA() {
int localA, localB;
localA = subX();
localB = localA;
subY(localB);
}
|
The Out of Step Variables report finds these read-then-set uses of global or static variables within tasks.
Out-of-Step (Z) Variables (Read Before Being Set)
Key:
r or R (letter): variable is read
s or S (letter): variable is set
S or R (upper case): variable is used in current function
s or r (lower case): variable is only used in called functions
rs (order): variable is read in at least one path before being set
sr (order): variable is set in all paths before being read
r* (order): variable is read first in at least one path;
it is set and read in various orders
s* (order): variable is set first in all paths where it is read;
it is set and read in various orders thereafter
RO (PTN): pattern of variable use across all tasks is read only
Z1 (PTN): pattern is status variable (only set to constants)
Z2 (PTN): pattern is aggregation variable
(assignments involve its own value)
Z3 (PTN): pattern is external data variable (array set to constants
and likely written to externally like DMA)
Settings:
Global Variables: displayed
Static Variables: displayed
Unset Variables: displayed
Struct Container Summary: omitted
Union/Bitfield Members: separate
Show Z-var Design Pattern: displayed
Task Definitions
Tasks are from User Defined Tasks
Name Members Graph Root
Task A 3 [+] taskA
Variable PTN Func1 Func2 Func3 (order of calls)
Task: Task A
taskA
. subX
. . subY
-------------------------------------------------- = = =
globalA .......................................... rs R S
|
Design Patterns
Some of the identified out-of-step variable usage in your software might conform to standard design patterns that can be considered acceptable usage. The PTN column of the report indicates when the use of a variable fits one of these patterns. You can quickly confirm such usage and then focus your review on the reported variable uses that don't match the patterns.
Z1 - Status Variable
The Z1 pattern refers to a global variable that is used to tell the task what status the system was in previously. The task reads the variable first in an if statement and then sets the status to another value. The status variable is never used in the calculation of any other variable.
int Status = 0;
void task_Z1a1() {
if (Status) {
/* Status is read first in "if" or
"switch" but not in a calculation */
SomeAction();
Status = 0; /* Status set to constant */
}
}
void task_Z1a2() {
int thisHappened;
thisHappened = SomeValue();
if (thisHappened) {
Status = 1;
}
}
|
A second case of Z1 pattern involves task requests. A task or external process sets a variable in order to cause an action in a second task. The second task checks the variable to see if there is something to do. If so, it performs the action and resets the action request variable.
int Action = 0;
int ActionParam;
void task_Z1b1() {
Action = 1;/* task requests action */
ActionParam = SomeValue();
}
void task_Z1b2() {
switch (Action) {
/* task checks for action */
case 1:
SomeAction1(ActionParam);
Action = 0; /* resets action code */
break;
case 2:
SomeAction2(ActionParam);
Action = 0;
break;
}
}
|
| Type of Variable | Single (no array, no struct member); int or enum |
| Tasks Using Variable | One or multiple |
| Use Patterns | Either RS or S |
| Conditions on Reads | In if or switch condition only |
| Conditions on Sets | Only constants are assigned |
Z2 - Aggregation Variable
The Z2 pattern identifies the situation where one task aggregates values in a variable over several cycles. For example, the task might add the values to the same variable in every cycle, or insert the values into an array and thereby increase the index in every cycle, or check if the value tracked in the variable is greater than a maximum. In each of these cases, the task will first read the variable that is used to aggregate the values and then set it. A second task will eventually read this aggregated variable and use it in its calculations. The second task might then reset it so that a new aggregation cycle can start.
Example Z2a with an out-of-step single variable (scalar) where value is added to aggregate in every cycle:
int AggregateCounter = 0;
double Aggregate = 0.0;
void task_Z2a1()
{
Aggregate += SomeFloatValue();
AggregateCounter++;
}
void task_Z2a2() {
if (AggregateCounter < 10) {
/* task evaluates aggregated value
from time to time */
double Calc;
Calc = SomeCalc(Aggregate);
/* resets aggregate variables */
AggregateCounter = 0;
Aggregate = 0.0;
}
}
|
Example Z2b with an out-of-step struct members where maximum value is tracked:
#define AGGRB 100
struct Aggr {
int AC;
double Max;
} GlobAggr = {0, 0.0};
void task_Z2b1() {
double val = SomeFloatValue();
if (val > GlobAggr.Max) {
GlobAggr.Max = val;
}
GlobAggr.AC++;
}
void task_Z2b2() {
if (GlobAggr.AC >= AGGRB) {
/* task displays max */
Display(GlobAggr.Max);
/* resets aggregate variables */
GlobAggr.AC = 0;
GlobAggr.Max = 0.0;
}
}
|
Example Z2c with an out-of-step array where values are inserted in every cycle within a single task:
#define AGGRC 100
int AC = 0;
double AggregateC[AGGRC]; /* Z-var */
double SomeCalc(double[]);
void task_Z2c() {
if (AC >= AGGRC) {
/* task evaluates aggregated value */
double Calc;
Calc = SomeCalc(AggregateC);
/* resets aggregate variables */
AC = 0;
}else {
if (AC > 0) {
/* track two point moving average */
AggregateC[AC] = (AggregateC[AC-1] +
SomeFloatValue()) / 2;
}else {
AggregateC[AC] = SomeFloatValue();
}
AC++;
}
}
|
| Type of Variable | Single, array, struct member; any type |
| Tasks Using Variable | One or multiple |
| Use Patterns | RS or S |
| Conditions on Reads | Either operation that involves its own value (++, --, +=, -=, &=, compare and set) or in if condition or calculation followed by reset to constant value |
| Conditions on Sets | Either operation that involves its own value (++, --, +=, -=, &=) or reset to constant value
|
| Further Notes | Aggregation count-up and reset can either happen in same task or in separate tasks |
Z3 - External Data Variable
The Z3 pattern identifies situations such as where sensor hardware writes directly to memory and the task reads the memory. Normally, this would not be flagged as an out-of-step variable in the report because the access would be read-only. However, in some designs, the task also resets (part of) the memory when it is done. In such cases, the variable usage is listed as out-of-step and indicated with the Z3 flag.
/* variable for DMA area */
volatile int DMAVar[128];
void task_Z3()
{
if (DMAVar[0]) {
/* DMA puts ready indicator there */
SomeAction(DMAVar);
DMAVar[0] = 0;
}
}
|
| Type of Variable | Array |
| Tasks Using Variable | One |
| Use Patterns | RS |
| Conditions on Reads | First read is in if condition followed by more reads in calculations |
| Conditions on Sets | Reset to constant value |
| Further Notes | This design pattern is very similar to Z1-Status Variable. The difference is that this is an array and allows multiple reads in calculations afterwards. |
|
