torx-adaptor(5) - a program that implements an interface to the SUT
Table of Contents
torx-adaptor - a program that implements an interface to the SUT
ADAPTOR
In this man page we discribe the interface of the ADAPTOR module.
The interface is very similar to the one of the PRIMER (See torx-primer(5)).
When active, the ADAPTER receives commands from the standard input and
writes answers in return to the standard output. See section COMMANDS
for the available commands and answers. When the ADAPTER is used in the
TORX tool it is connected to the DRIVER which has the control and initiative
of all communications. When the ADAPTER is used standalone the user plays
the role of the DRIVER.
A command consist of a single line of text. The
keyword (the first word) of each commands start with a prefix C_.
An answer
consist of a single line of text or a multi-line of text. All single-line
answers start with a keyword that has prefix A_. Usually, the keyword of
single-line answer is identical to the command-keyword, but with the C_ replaced
by A_. A multi-line answer has specific markers around the body of the answer.
These markers consist of a single line that starts with a prefix A_, followed
by the command-keyword without the initial C_, followed by _START respectively
_END. Each line of the body of a multi line answer often starts with a keyword
(but not always).
Instead of the usual single- or multi-line answer, an A_ERROR
answer may occur in case of an error. Such an A_ERROR answer comes instead
of the usual single- or multi-line answer.
Additional message lines containing
warnings (to be shown to the test run operator), diagnostics (to appear
in the test run log), and/or debugging output (to be shown to the test
run operator) may appear interspersed with the answer lines described so
far. These message lines start with A_WARNING, A_LOG or A_DEBUG, respectively.
Because these message lines may appear arbitrarily intermixed with the
``regular'' answer line(s), they do not play a role when the ``end'' of an answer
has to be found: once the command-specific answer or A_ERROR answer has
been read, the user of the ADAPTER may assume that no other output (specific
to to the command) will be generated by the ADAPTER until the next command
is send to it.
If the ADAPTOR decides autonomously that it will stop executing,
it may try to indicate this by sending an A_QUIT answer, just before exiting.
For the ADAPTOR, reading end-of-file on its standard input is a reason to
stop executing.
In all cases, each command and each answer starts with a
keyword that is separated from the remainder of the line by one or more
spaces or tabs - except for two notable exceptions: A_ERROR, where currently
exactely one space should be between the keyword and the category, and
the lines between A_STATE_START and A_STATE_END, that do not start with
a keyword (see DETAILS below). For most comands and most 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 line is as follows: the keyword
is followed by a (possibly empty) TAB-separated list of name=value items,
where the name cannot contain TABs or = characters, and the value cannot
contain TAB characters. 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 the users can simply 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.
For A_ERROR answers,
currently the format is as follows: the A_ERROR keyword is followed by
a category word indicating the category of the error, followed by arbitrary
text that describes the error in more detail. The idea is that the user
of the ADAPTOR can use the category word to get some idea of the nature
of the error. In particular, the idea is that the user can use this to decide
whether it makes sense to retry, or whether it is better to give up.
Here
we describe first the syntax of the (textual) messages interchanged over
the interface, followed by the possible message arguments, followed by
the possible error categories.
Below we describes the syntax of the
commands and answers, by giving the syntax of just a single interaction.
- 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 space category : text-upto-end-of-line nl
- arguments-upto-end-of-line:
- ws* | ws+ arguments
- arguments:
- argument | argument tab arguments
- argument:
- name = value
/* value can contain spaces but no tabs */
- text-upto-end-of-line:
- ws* | ws+
arbitrary-text-without-newline
- ws:
- space | tab
At the moment the
following names are defined for the name=value arguments to the commands:
- 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)
- pco
- with as value a pco name;
- concrete
- with as value a (string
representation of the) concrete value (this string cannot contain tab or
new-line characters);
- timestamp
- with as value a (string representation of
the) time
At the moment, for the A_ERROR category messages given
by the ADAPTER, the following categories are defined. The user of the ADAPTER
(i.e. torx) may use these categories to decide how to react to the A_ERROR
answer (in particular, to decide whether it can cope with it, or whether
it is better to give up).
- UnknownCommand
- the command is not known
- ArgumentMissing
- a mandatory argument of the command is missing or incomplete
- WrongValue
- the value of an argument of the command is outside its domain of valid
values
- ParseErrorEvent
- the command contains an event argument which cannot
be parsed
- UnknownIOKind
- the command contains an event argument, and the
iokind of the event cannot be computed
- Inconsistency
- the command contains
more than a single argument, and the values of (some of) the arguments
conflict which each other
- InternalError
- an internal error occurred
during the execution of the command
Below follows the list of the
commands. The commands, and their answers, are described in more detail
below. With each command, and answer, the possible arguments are indicated.
Optional arguments are surrounded by brackets '[' and ']'. Note: the order in
which the arguments are named with the commands does not prescribe the
order in which arguments may appear: arguments may appear in any order.
C_CHANNELS [iokind] [channel]
C_PCOS [iokind] [channel] [pco]
C_IOKIND [iokind] [channel]
C_INPUT channel event
C_OUTPUT channel
C_STATE
C_STATES
C_QUIT
C_GETCONFIG
The C_INPUT and C_OUTPUT commands are the most important ones,
and have to be implemented correctly for TorX to work correctly; the other
commands are less important, and most of them are mainly used to get configuration
information from the ADAPTOR, only for logging purposes.
In the subsections
below, each command is followed by a short explanation of its use. Additional
comments are enclosed between /* and */ after the command.
The C_CHANNELS
command is used to ask the ADAPTOR 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 applied without changing
the state of the ADAPTOR module.
- Command:
- C_CHANNELS [iokind] [channel]
- Answer (multi-line):
- A_CHANNELS_START
A_CHANNEL iokind channel
...
A_CHANNELS_END
- Errors (single-line):
- A_ERROR Inconsistency /*if the iokind
and channel fields conflict*/
A_ERROR WrongValue /*if a given field has value outside domain*/
The
C_PCOS command is used to ask the ADAPTOR which pcos exist. If a pco is
used both for input and output, then there will be two A_PCO lines for
it, one with iokind=input and the other with iokind=output. If the iokind,
channel and/or pco argument is used, then only the respective pcos are
returned. This command has no side-effects, and can repeatedly be given without
changing the state of the ADAPTOR module.
- Command:
- C_PCOS [iokind] [channel]
[pco]
- Answer (multi-line):
- A_PCOS_START
A_PCO iokind channel pco
...
A_PCOS_END
- Errors (single-line):
- A_ERROR Inconsistency /*if the iokind,
channel and pco fields conflict*/
A_ERROR WrongValue /*if a given field has value outside domain*/
The
C_IOKIND command is used to ask the ADAPTOR whether the ADAPTOR has a preference
for the next action to be an input or an output action, or wether the ADAPTOR
doesn't care, and any action kind is possible. The idea of this command is
to allow the ADAPTOR to indicate that it has observations qeueued. The command
can have an optional suggestion, which will be honoured by the ADAPTOR
if possible. This command has no side-effects, and can repeatedly be given
without changing the state of the ADAPTOR module. If the ADAPTOR doesn't
care about the action kind when no suggestion was given, it simplu should
not return iokind nor channel paratmers in the A_IOKIND answer.
- Command:
- C_IOKIND [iokind] [channel]
- Answers (single-line):
- A_IOKIND iokind channel
A_IOKIND /*if adaptor doesn't care and no sugg. given*/
- Errors (single-line):
- A_ERROR Inconsistency /*if the iokind and channel fields conflict*/
A_ERROR WrongValue /*if a given field has value outside domain*/
The
C_INPUT command is used to ask the ADAPTOR to stimulate with a given action.
If the action given cannot be parsed, or if other errors occur when trying
to ``do'' the action, the ADAPTOR will return A_ERROR (with an explanation
of the error), and no action will be done; if the action can be parsed,
but is not ``enabled'' (i.e. is not in the ``menu of possible input actions of
the IUT''), and therefore cannot be ``done'', the ADAPTOR will return A_INPUT_ERROR,
and no action will be done; otherwise the ADAPTOR will return A_INPUT with
the action that has been ``done'', if possible including the pco on which the
action was done, a timestamp, and the concrete representation of the action.
Questions: are we now mapping input-suspension onto A_INPUT_ERROR? Should
we get rid of A_INPUT_ERROR here, and use either A_ERROR (for IOCO) or
A_INPUT_OK with suspension=1 (for MIOCO)? Note: currently, it is best to
avoid using A_INPUT_ERROR; use A_ERROR instead.
- Command:
- C_INPUT channel
event
- Answers (single-line):
- A_INPUT_OK channel event [pco] [timestamp]
[concrete-event]
A_INPUT_ERROR /*if event cannot be done*/"
- Errors (single-line):
- 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*/
The C_OUTPUT
command is used to ask the ADAPTOR for an observation on a given channel.
If observing fails, the ADAPTOR will return A_ERROR (with an explanation
of the error). Otherwise, the ADAPTOR will return A_OUTPUT_OK with the observation,
if possible including the pco on which the observation was done, a timestamp,
and the concrete representation of the observation.
- Command:
- C_OUTPUT channel
- Answer (single-line):
- A_OUTPUT_OK channel event [pco] [timestamp] [concrete-event]
- Errors (single-line):
- A_ERROR ArgumentMissing /*if no event was given
to IOCO or traces*/
A_ERROR UnknownIOKind /*if iokind of event cannot be found*/
A_ERROR WrongValue /*if a given field has value outside domain*/
A_ERROR InternalError /*if internal error occurred*/
The C_STATE
command returns a textual representation of the current state. The contents
of this textual representation depend on the implementation of the ADAPTOR.
This command has no side-effects.
- Command:
- C_STATE
- Answer (multi-line):
- A_STATE_START
text ...
...
A_STATE_END
The C_STATS command returns some statistics about the
ADAPTOR. 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. An ADAPTOR should give just one line
of statistics (both single- and multi-line form are allowed).
- Command:
- C_STATS
- Answer (single-line):
- A_STATS statistics
- Answer (multi-line):
- A_STATS_START
A_STATS statistics
...
A_STATS_END
The C_QUIT command tells the ADAPTOR to clean up and exit.
The ADAPTOR will acknowledge the command with A_QUIT. The side-effect of
this command is that the ADAPTOR module exits.
- Command:
- C_QUIT
- Answer (single-line):
- A_QUIT
This command has not been implemented yet. It is to be used
to get configuration information from the ADAPTOR.
For
the implementer of an adapter, the most important commands to implement
are C_INPUT and C_OUTPUT. Commands C_INPUT and C_OUTPUT are needed so the
driver can stimulate and observe.
The C_IOKIND command is important, because
if it is implemented in the wrong way, the user can no longer control the
tester with the commands in torx(1) or the buttons in xtorx(1). The best
default implementations for C_IOKIND are those that either returns A_IOKIND
with the same parameters that were given with the C_IOKIND command, or
just returns A_IOKIND without parameters.
If the C_PCOS command is implemented
such that it indeed returns a list of the pcos, and the pco parameter is
used for the A_INPUT_OK and A_OUTPUT_OK answers, then TorX is able to draw
better Message Sequence Charts.
For all the other commands, the implementer
can choose to give simple answers, by returning just the answer keyword
without parameters, for single-line answers, and returning just the answer
start and answer end keywords for multiline answers. Of course, more informational
answers proved more feedback during testing, and may make it more easy
to investigate in case of errors -- the information above is mainly meant
to make it easier to quickly implement a ``basic'' adapter that already ``does
the right thing''.
torx-intro(1), mkprimer(1), torx-primer(5), torx-config(4),
torx-log(4), torx(1), sh(1)
By Email: <torx_support@cs.utwente.nl>
This
manual page documents version 3.9.0 of torx.
Table of Contents
|
Prev
|
Table of Contents
|
Next
|
|
Appendix D: TorX Manual Pages: mkprimer(5) - support specification language or toolkit
|
|
Appendix D: TorX Manual Pages: torx-explorer(5) - interface to program to explore a labelled transition
|