Click or drag to resize

12.5.3.1 Flow-Control within the current Command List

The following Flow-Control Commands are available for altering the sequence of execution within the current command list.

Note  Note

Most intra-list Flow-Control Commands take an integer parameter which specifies the position of the target command, i.e. index of the target command within the current CommandList. It is generally the application's business to ensure that correct index values are specified.

However, keeping track of forward references from Branch commands to the locations of as yet undefined target commands can become tedious, and require "ingenious" programming.

Consequently, certain Flow-Control Commands are implemented with variants that accept labels for their target definitions.

Please refer to 12.5.3.3 Flow-Control using Labels within the current Command List for more details.


The notional End-Of-List (EOL) position, i.e. "one past the last command", may be used as valid target for intra-list Branch and Goto commands.
However, here also it can be difficult to calculate the necessary offset of EOL, especially when the list is being constructed dynamically.

Unconditional Branch within current list

An unconditional branch is used to force a deviation from the normal sequence of execution within the current list.

Roughly equivalent to:
Copy
goto someLineNumber;

ListAPI Method

SP-ICE-3 Command

AppendBranchAbs(Int32)

BRANCH_ABS

AppendBranchRel(Int32)

BRANCH_REL

Conditional Branch within current list.

A conditional branch may be used to allow a choice, dependent upon the condition or value read from an I/O Port, or on the state of a boolean flag variable, between two alternative continuations of the sequence of execution within the current list.

Roughly equivalent to:
Copy
if (IOPort.Read() == CONDITION) goto someLineNumber;

// or

if (flagVariable == true) goto someLineNumber;

ListAPI Method

SP-ICE-3 Command

AppendBranchAbs(Int32, UInt32, IOPort, Boolean, Boolean, UInt32)[COND]

BRANCH_ABS_COND

AppendBranchAbs(Int32, String, Boolean)[FLAG]

BRANCH_ABS_COND_FLAG

AppendBranchRel(Int32, UInt32, IOPort, Boolean, Boolean, UInt32)[COND]

BRANCH_REL_COND

AppendBranchRel(Int32, String, Boolean)[FLAG]

BRANCH_REL_COND_FLAG

Switch Command within current list.

A switch command may be used to allow the selection, dependent upon the condition or value read from an I/O Port, or upon the value of an integer variable, of any one of several possible continuations of the sequence of execution within the current list.

Roughly equivalent to:
Copy
switch (IOPort.Read()) {        // SWITCH

case condA: goto lineNumA;    // CASE_GOTO

case condB: goto lineNumB;    // CASE_GOTO

// etc

default: goto lineNumC;        // DEFAULT_GOTO

}

lineNumA:
// more commands here

lineNumB:
// further commands here

lineNumC:
// even more commands here

ListAPI Method

SP-ICE-3 Command

AppendSwitch(IOPort, Boolean, UInt32)[PORT]

SWITCH

AppendSwitch(String)[VAR]

SWITCH_VALUE

AppendCaseAbs(Int32, UInt32)[COND]

CASE_GOTO_ABS

AppendCaseRel(Int32, UInt32)[COND]

CASE_GOTO_REL

AppendCaseAbs(Int32, Int32)[VAL]

CASE_GOTO_ABS

AppendCaseRel(Int32, Int32)[VAL]

CASE_GOTO_REL

AppendDefaultAbs(Int32)

DEFAULT_GOTO_ABS

AppendDefaultRel(Int32)

DEFAULT_GOTO_REL

Exit List Commands: early termination of current list.

An unconditional or unconditional exit command can be used to force execution of the current list to finish before the reaching the end of the list.

Roughly equivalent to:
Copy
void mainList()
{
// do some main stuff

// check an early termination condition
if (IOPort.Read() == CONDITION) return;    // EXIT_LIST

// do more stuff

// check another early termination condition
if (flagVariable == true) return;    // EXIT_LIST_FLAG

// do even more stuff

// normal end of list here
}

ListAPI Method

SP-ICE-3 Command

AppendExitList

EXIT_LIST

AppendExitList[PORT]

EXIT_LIST

AppendExitList[VAR]

EXIT_LIST_FLAG

See Also