[ Home \| What's New \| Contents \| Overview \| Contributors \| Distribution \| Examples \| Documentation \| Manual \| Publications \| Mailing List Archive \| Problems ]		This page was last updated by Axel Belinfante on 2006-01-19
TorX Test Tool Information
Prev		Next

torx-primer(5) - interface to program that derives test primitives from

Table of Contents

Name

torx-primer - interface to program that derives test primitives from

labelled transition system

In this man page we discribe the interface of the PRIMER module. The PRIMER module, a UNIX program together with the EXPLORER module, implements an (textual) interface of a labelled transition system (lts).

When active, the PRIMER receives commands from the standard input and writes answers in return to the standard output. See section COMMANDS and ANSWERS for the available commands and answers. When the PRIMER is used in the TORX tool it is connected to the DRIVER which has the control and initiative of all communications. When the PRIMER is used as standalone the user plays the role of the DRIVER.

A command consist of a single line of text. The keyword of all commands start with a prefix C_.

A answer consist of a single line of text or a multi-line of text. All single line answers start with a prefix A_. A multi-line answer has specific markers around the body of the answer. These markers consist of a single keyword at a single line, made up from the usual answer keyword, with _START and _END appended, respectively. Each line of the body of a multi line answer often starts with a keyword (but not always). Usually, the PRIMER answers to a command with the identical command-keyword, but with the C_ replaced by A_. Instead of the usual answer, an A_ERROR answer may occur in case of an error.

The following describes the syntax of the commands and answers:

interaction:

message* command message* answer-or-error

command:

C_name arguments-upto-end-of-line nl

answer-or-error:

single-line-answer | multi-line-answer | error

single-line-answer:

A_name arguments-upto-end-of-line nl

multi-line-answer:

A_name_START nl multi-line-element* A_name_END nl

multi-line-element:

message | result-element

result-element:

A_element-name arguments-upto-end-of-line nl

message:

debug | log | warning

debug:

A_DEBUG text-upto-end-of-line nl

log:

A_LOG text-upto-end-of-line nl

warning:

A_WARNING text-upto-end-of-line nl

error:

A_ERROR text-upto-end-of-line nl

For some commands and some answers, the text following the keyword has a fixed format; for other commands and answers it is left unspecificed.

For command and answers that deal with channels, events, predicates, etc. the format of each such line is as follows: the keyword is followed by a (possibly empty) TAB-spearated list of name=value items, where the name cannot contain TABs or = characters, and the value cannot contain TAB characters. Note that the order of the name=value items is left unspecified, i.e. they may appear in any order, even though the presentation below, in the detailed specification of the commands and their answers, might suggest otherwise. For the moment we assume that, when necessary, we will encode TAB characters for example using C conventions. We have chosen for this kind of item-lists because this makes it easy to pass information. Using name=value pairs instead of (for example) a list of values in a fixed order makes the interface more robust: the order of items is not important, and, provided the users ignore items which name they don't recognize. This allows one party to send items which the receiving party doesn't know about. This makes it easier to extend the interface by adding new items and keeping old programs backwards compatible.

At the moment the following names of the name=value items, are defined:

event

with as value the LOTOS-like string representation of an event, used wherever ``event'' is used below;

channel

with as value a channel name;

iokind

where iokind is a value input or output;

suspension

with as value either ``0'' or ``1'' to indicate a non-suspension resp. suspension event, used wherever an output ``event'' is used below (in the future we expect to use it also for input events)

super

with as value a number that is used to represent a state-vector;

init

with as value a comma-separated list of those state numbers that were directly reached by an observable transition;

trans

with as value a comma-separated list of those state numbers that were reached from init via (an) internal (non-observable) transition(s).

Note1:

``predicates'' is currently only implemented in the generic primer(1).

Note2:

we may want to split the ``predicates'' into two (or more?) groups, depending on the complexity of the operation that we want (need) to perform on them. We could for example have one group that consists of equations, for which we need a single solution (witness), and another group consists of equations, for which we need proof that no solution exists.

Note3:

The lists of comma-separated state numbers of init and trans may contain abbreviations of the form first-last as abbreviation of strictly increasing sequences of the form first, (first+1), (first+2), ..., (last-2), (last-1), last, where last is equal to or greater than (first+1).

Answers are outputted after the receival of a command, but always before the command-specific answer or A_ERROR answer. I.e. once the command-specific answer or A_ERROR answer has been read, the user of the PRIMER may assume that no other output will be generated by the PRIMER until the next command is send to it.

Besides the "normal" (expected) answers the PRIMER can also respond with error and warning messages as answers.

Currently known errors:

A_ERROR UnknownCommand

A_ERROR ArgumentMissing
/*if arguments are missing or incomplete*/

A_ERROR ParseErrorEvent
/*if the event cannot be parsed*/

A_ERROR UnknownIOKind
/*if iokind of event cannot be found*/

A_ERROR Inconsistency
/*if fields conflict*/

A_ERROR WrongValue
/*if a given field has value outside domain*/

A_ERROR InternalError
/*if internal error occurred*/

In principle, each answer of the PRIMER can contain one or more diagnostic lines, indicating errors, warnings, end-of-test, or guidance information. Below some examples of ansers:

A_WARNING

A_EOT

A_GUIDANCE_VERDICT INCONSISTENT

A_GUIDANCE_VERDICT INCONCLUSIVE

A_GUIDANCE_VERDICT PASS

For logging of debugging information the following answers may appear anywhere.

A_DEBUG

A_LOG

Options

The PRIMER module support the following commandline options:

-s number: the seed for the random number generator
-i gates1,gate2,gate3,...: the list of input gates. Note there are no spaces between the gates!
-o gates1,gate2,gate3,...: the list of output gates. Note there are no spaces between the gates!
-S algorithm: the algorithm which can be ioco, traces or simulation. By default this is ioco. Note that this option is only implemented in LOTOS PRIMERs.
-d delta-event-tag: the delta-event-tag is used for quiescense in the interface. By default the tag is ``Delta''. Note that this option is not needed for the traces algorithm, and that this option is only implemented in the LOTOS PRIMERs.

COMMMANDS and ANSWERS

The core functionality of the PRIMER is given by the following commands which use the syntax described above (DESCRIPTION). (The brackets [ and ] indicate optional elements):

C_IOKIND [iokind] [channel]

C_GETINPUT [channel] [event] [predicates]

C_INPUT [channel] [event] [predicates]

C_OUTPUT [channel] [event] [predicates]

C_QUIT

Below follows the list of the all commands, which are described in more detail in the following subsections:

C_CHANNELS [iokind] [channel]

C_IOKIND [iokind] [channel]

C_GETINPUT [channel] [event] [predicates]

C_INPUT [channel] [event] [predicates]

C_GETOUTPUT [channel] [event] [predicates]

C_OUTPUT [channel] [event] [predicates]

C_INPUTS [channel]

C_OUTPUTS [channel]

C_STATE

C_STATEID

C_GOTO [super]

C_STATS

C_QUIT

C_GUIDANCE_INFO

C_GUIDANCE_QUIT

C_GETCONFIG

C_EOT

In the subsections below each command is followed by a short explanation of its use. Additional comments are enclosed between /* and */ after the command.

Channels

This command has only been implemented for the Smile PRIMER. The C_CHANNELS command is used to ask the PRIMER which channels exist. If the iokind and/or channel argument is used, then only the respective channels are returned. This command has no side-effects, and can repeatedly be given without changing the state of the EXPLORER and PRIMER modules.

Commands:

C_CHANNELS [iokind] [channel]

Answers:

A_CHANNELS_START
A_CHANNEL iokind channel ...
...

A_CHANNELS_END

A_ERROR Inconsistency
/*if the iokind and channel fields conflict*/

A_ERROR WrongValue
/*if a given field has value outside domain*/

where iokind is either INPUT or OUTPUT.

Iokind

The C_IOKIND command is used to ask the PRIMER whether the next action should be an input or an output action. The command can have an optional suggestion, which will be honoured by the PRIMER if possible. This command has no side-effects (apart from calling the random number generator), and can repeatedly be given without changing the state of the EXPLORER and PRIMER modules.

Commands:

C_IOKIND [iokind] [channel]

Answers:

A_IOKIND iokind channel

A_ERROR Inconsistency
/*if the iokind and channel fields conflict*/

A_ERROR WrongValue
/*if a given field has value outside domain*/

where iokind is either INPUT or OUTPUT.

Getinput

The C_GETINPUT command is used to ask the PRIMER for an input transition without doing a transition (the transition is done with the C_INPUT command). The command can have an optional suggestion for the action, which will be honoured by the PRIMER if the action is in the current list of input actions; if no action is given, an action will be randomly chosen from the 'current' list of input actions. If the action given as suggestion cannot be parsed, the PRIMER will return A_ERROR (with an explanation of the error); otherwise it will return the given or chosen action.

Commands:

C_GETINPUT [channel] [event] [predicates]

Answers:

A_GETINPUT_OK channel event predicates

A_GETINPUT_ERROR
/*if event is not in menu*/

A_ERROR ParseErrorEvent
/*if the event cannot be parsed*/

A_ERROR ArgumentMissing
/*if no event was given to simulator*/

A_ERROR UnknownIOKind
/*if iokind of event cannot be found*/

A_ERROR Inconsistency
/*if the iokind and channel fields conflict*/

A_ERROR WrongValue
/*if a given field has value outside domain*/

A_ERROR InternalError
/*if internal error occurred*/

Input

The C_INPUT command is used to ask the PRIMER to do an input transition. The command is given the action that has to be done, which should be in the current list of input actions (if not, A_INPUT_ERROR will be returned). If the action given cannot be parsed, the PRIMER will return A_ERROR (with an explanation of the error), and no transition will be done; otherwise it will return the action that is 'done'.

Commands:

C_INPUT [channel] event [predicates]

Answers:

A_INPUT_OK channel event predicates

A_INPUT_ERROR
/*if event is not in menu*/

A_ERROR ParseErrorEvent
/*if the event cannot be parsed*/

A_ERROR ArgumentMissing
/*if no event was given*/

A_ERROR UnknownIOKind
/*if iokind of event cannot be found*/

A_ERROR Inconsistency
/*if the iokind and channel fields conflict*/

A_ERROR WrongValue
/*if a given field has value outside domain*/

A_ERROR InternalError
/*if internal error occurred*/

Getoutput

The C_GETOUTPUT command is used to ask the PRIMER for an output transition without doing a transition (the transition is done with the C_OUTPUT command). If the command does not contain an action, the SIMULATOR will randomly choose an action, and the IOCO and traces version will return an error message; if the command does contain an action, the PRIMER will check if it can 'do' the action (but will not actually do the action). If the action cannot be parsed, the PRIMER will return A_ERROR (with an explanation of the error). Otherwise, if the action can be performed, the PRIMER will return A_GETOUTPUT_OK; if the action cannot be performed (i.e. if the action is not in the list of current output actions) A_GETOUTPUT_ERROR will be returned.

Commands:

C_GETOUTPUT [channel] [event] [predicates]

Answers:

A_GETOUTPUT_OK channel event predicates

A_GETOUTPUT_ERROR
/*if the event is not in menu of IOCO */

A_ERROR ParseErrorEvent
/*if the event cannot be parsed*/

A_ERROR ArgumentMissing
/*if no event was given to IOCO or traces*/

A_ERROR UnknownIOKind
/*if iokind of event cannot be found*/

A_ERROR Inconsistency
/*if the channel and event fields conflict*/

A_ERROR WrongValue
/*if a given field has value outside domain*/

A_ERROR InternalError
/*if internal error occurred*/

Output

The C_OUTPUT command is used to ask the PRIMER to do an output transition. If the command does not contain an action, the SIMULATOR will randomly choose which action to do, and the IOCO and traces version will return an error message; if the command does contain an action, the PRIMER will attempt to 'do' the action. If the action cannot be parsed, the PRIMER will return A_ERROR (with an explanation of the error). Otherwise, if the action can be performed, the PRIMER will return A_OUTPUT_OK; if the action cannot be performed (i.e. if the action is not in the list of current output actions) A_OUTPUT_ERROR will be returned.

Commands:

C_OUTPUT [channel] [event] [predicates]

Answers:

A_OUTPUT_OK channel event predicates

A_OUTPUT_ERROR
/*if the event is not in menu of IOCO */

A_ERROR ParseErrorEvent
/*if the event cannot be parsed*/

A_ERROR ArgumentMissing
/*if no event was given to IOCO or traces*/

A_ERROR UnknownIOKind
/*if iokind of event cannot be found*/

A_ERROR Inconsistency
/*if the channel and event fields conflict*/

A_ERROR WrongValue
/*if a given field has value outside domain*/

A_ERROR InternalError
/*if internal error occurred*/

Inputs

The C_INPUTS command returns the list of current input actions. This list can be restricted with the optional channel argument. This command has no side-effects.

Command:

C_INPUTS [channel]

Answer (multi-line):

A_INPUTS_START
A_EVENT channel event predicates
...
A_INPUTS_END

A_ERROR WrongValue
/*if a given field has value outside domain*/

A_ERROR Inconsistency
/*if the channel has wrong iokind*/

Outputs

The C_OUTPUTS command returns the list of current output actions. This list can be restricted with the optional channel argument. This command has no side-effects.

Command:

C_OUTPUTS [channel]

Answer (multi-line):

A_OUTPUTS_START
A_EVENT channel event predicates
...
A_OUTPUTS_END

A_ERROR WrongValue
/*if a given field has value outside domain*/

A_ERROR Inconsistency
/*if the channel has wrong iokind*/

State

The C_STATE command returns a textual representation of the current state. The contents of this textual representation depend on the implementation of the PRIMER. For the Open/Caesar implementation, the representation consists of two lines of 'legenda', followed by a line for each state in the current 'state-vector'. This command has no side-effects.

Command:

C_STATE

Answer (multi-line):

A_STATE_START
text ...
...
A_STATE_END

Stateid

The C_STATEID command returns the current state identifier. The state identifier consists of a single number (super) that represents (identifies) the current state(-vector), together with a list of comma-separated state numbers of those states in the current state(-vector) that were directly reached via an observable transition (init), and a list of comma-separated state numbers of those states in the current state(-vector) that were reached from the init states via an internal (non-observable) transition (trans). In the lists of state numbers (sub)sequences of strictly increasing state numbers, where each element in the sequence is equal to the previous element plus one, may be abbreviated to first-last with first and last the first and last elements of the (sub)sequence. A PRIMER should give just one line state identifier (both single- and multi-line form are allowed). The COMBINATOR combines the state identifier of its primers, by giving the lines of its primers in a multi-line answer. When it does so, it prefixes the statistics of each primer with a name-value field identity that contains a white-space separated list of two white-space separated name-value pairs: one that gives the id of the primer (key: id) and a second one that gives the role of the primer (key: role, values: SPEC, GUIDE, TEST), both as specified in the configuration value of the combinator. This command has no side-effects.

Command:

C_STATEID

Answer (single-line):

A_STATEID super init trans

Answer (multi-line):

A_STATEID_START
A_STATEID identity super init trans

...
A_STATEID_END

Goto

The C_GOTO command goes to the state identified by the given super state identifier. This state identifer must have been retrieved earlier using a STATEID command. This command does have a side-effect.

Command:

C_GOTO super

Answer (single-line):

A_GOTO_OK

A_GOTO_ERROR A_GOTO_ERROR UnknownStateID super
/*if an unknown super state was given*/

A_ERROR ArgumentMissing
/*if no super field was given*/

Note that the GOTO command is a rather recent addition. As an unfortunate result of that, the A_GOTO_ERROR response currently has different parameters in the various implementations that we have. The CADP primer only returns A_GOTO_ERROR, whereas the 'generic' primer also returns the string UnknownStateID and the failing argument super state. We hope to make this more uniform once we have more experience with this interface command.

Stats

The C_STATS command returns some statistics about the PRIMER (like: numer of states in state-vector, number of explored states, number of transitions etc.). The statistics consists of a list of whitespace-separated key-value pairs, where also the key and the value are separated by whitespace. The value should not contain whitespace. A PRIMER should give just one line of statistics (both single- and multi-line form are allowed). The COMBINATOR combines the statistics of its primers, by giving the lines of its primers in a multi-line answer. When it does so, it prefixes the statistics of each primer with two name-value pairs: one that gives the id of the primer (key: id) and a second one that gives the role of the primer (key: role, values: SPEC, GUIDE, TEST), both as specified in the configuration value of the combinator.

Command:

C_STATS

Answer (single-line):

A_STATS statistics

Answer (multi-line):

A_STATS_START
A_STATS statistics

...
A_STATS_END

Quit

The C_QUIT command tells the PRIMER to clean up and exit. The PRIMER will acknowledge the command with A_QUIT. The side-effect of this command is that the PRIMER module exits.

Note: when this command is send to the COMBINATOR it will send a C_QUIT command to each of the PRIMERs that it controls, and then clean up and exit, without waiting for the responses of the PRIMERs. In this respect this command differs from the C_GUIDANCE_QUIT command (see below).

Command:

C_QUIT

Answer:

A_QUIT

Guidance_info

This command is currently not used by the DRIVER; it has been implemented in the COMBINATOR. The C_GUIDANCE_INFO command asks the COMBINATOR to give the (tab-separated) ``id'' and ``role'' (SPEC, GUIDE, or TEST) for each of the PRIMERs that it is responsible for.

Command:

C_GUIDANCE_INFO

Answer:

A_GUIDANCE_INFO_START
A_GUIDANCE_INFO id role

...
A_GUIDANCE_INFO_END

Guidance_quit

This command is currently not used by the DRIVER; it has been implemented in the COMBINATOR. The C_GUIDANCE_QUIT command asks the COMBINATOR to send a C_QUIT command to each of the PRIMERs that it is responsible for, and wait for the answers. In this respect this command differs from the C_QUIT command (see above).

Command:

C_GUIDANCE_QUIT

Answer:

A_GUIDANCE_QUIT

Getconfig

This command has not been implemented yet. Get configuration information from the COMBINATOR (and via it, from its primers) or the primer.

Eot

This command is currently not used by the DRIVER; it has been implemented in the PRIMER and COMBINATOR. The C_EOT command asks the PRIMER whether 'end-of-test' has been reached. The PRIMER will return A_EOT_YES if the lists of current actions are empty, or if the list of input actions is empty and the list of output actions contains only `delta`. This command has no side-effects.

Command:

C_EOT

Answer:

A_EOT_YES

A_EOT_NO

Contact

By Email: <torx_support@cs.utwente.nl>

Version

This manual page documents version 3.9.0 of torx.

Table of Contents

Name
Synopsis
Description
Options
COMMMANDS and ANSWERS
See Also
Contact
Version

Prev	Table of Contents	Next
Appendix D: TorX Manual Pages: torx-instantiator(5) - a program that implements an instantiator		Appendix D: TorX Manual Pages: xtorx-extension(n) - api to specify the Mutants, Primers and Guides menus