===============================================================================
INTRODUCTION
===============================================================================

Here it is explained how to use the ocra tool. It provides a command line
interface and it is built on top of the NuSMV3 model checker.

ocra provides three commands:
  - ocra_check_syntax
  - ocra_check_refinement
  - ocra_check_implementation

In the following explanation, it is assumed the binary, the models and, if in a
windows environment, the provided dlls, to be in the same directory.

===============================================================================
INTERACTIVE MODE
===============================================================================
First thing, start a interactive session with ocra:

-------------------------------------------------------------------------------
In Unix-like systems:
shell $ ./ocra -int
ocra >

In Windows systems:
shell $ ./ocra.exe -int
ocra >
-------------------------------------------------------------------------------

In ocra, the help for any command can be obtained with the option -h, for
instance:

-------------------------------------------------------------------------------
ocra > ocra_check_refinement -h
usage: ocra_check_refinement [-h] [-i <file>] [-k <int>]
   -h Prints the command usage
   -i <file> input file
   -k <int> bound on length of path
   -a <string> force algorithm type
               Valid values are: bmc, fair_bmc, fair_bdd, bdd, undefined (default)

-------------------------------------------------------------------------------

To end an interactive session, use the command "quit".


===============================================================================
SIMULATING BATCH MODE
===============================================================================
When called by a program, there is more suitable way do it. It is indeed
possible to simulate a batch mode exploiting the pipelining. Here is an
example:

echo "set on_failure_script_quits; ocra_check_syntax -c -p \"<SOME CONSTRAINT \
>\"; quit" | ./ocra -int

The interactive session is entered as well, but the commands are pipelined in
it. Notice that the "set on_failure_script_quits" and "quit" commands are
needed to avoid the interactive session to stay active waiting for input.

This mode gives the user a easy way to check the result of the command; it is
enough to look at the error status.


===============================================================================
OCRA_CHECK_SYNTAX
===============================================================================
It checks the syntax of a model. In case of success, no output is returned;
otherwise, an error message is given.

The common usage is this:

-------------------------------------------------------------------------------
ocra > ocra_check_syntax -i WBS_propositional.oss
-------------------------------------------------------------------------------

For checking a constraint it is possible to use the alternate syntax:

-------------------------------------------------------------------------------
ocra > ocra_check_syntax -c -p <a constraint>
-------------------------------------------------------------------------------


===============================================================================
OCRA_CHECK_REFINEMENT
===============================================================================
First, it checks the syntax of a model. In case of success, no output is
returned; otherwise, an error message is given.
Second, it checks that a given system architecture is correct with respect to
the specified refinement of contracts. The verification guarantees that if the
implementations of the leaf components are correct, then for every composite
component C:
* every contract of C is satisfied by the implementations of the
  subcomponents of C
* every assumption of a subcomponent of C is satisfied by
  the implementations of the other subcomponents of C or by the environment of C.

If the check finds that the refinement is wrong, the system gives you a
counterexample. An example is provided in the file ocra_counterexample.txt.

Every check will end with one of the following answers:

[OK]       The check went fine
[BOUND OK] The check went fine, but bounded model checking was used, so the
           verification is not complete, but made up to the k specified (10 by
           default)
[NOT OK]   The check found an error. A counterexample is shown.

Example of use:

-------------------------------------------------------------------------------
ocra > ocra_check_refinement -i WBS_propositional.oss

Checking refinement of component: system
Checking "CONTRACT brake_time REFINEDBY bscu.cmd_time, bscu.safety, hydr.brake_time;"
Checking the correct implementation of "brake_time"... [OK]
Checking the correct environment of "bscu.cmd_time"... [OK]
Checking the correct environment of "bscu.safety"... [OK]
Checking the correct environment of "hydr.brake_time"... [OK]

Checking refinement of component: BSCU
Checking "CONTRACT cmd_time REFINEDBY bscu1.cmd_time, bscu2.cmd_time, switch.sel0_time, switch.sel1_time, bscu1.safety, bscu2.safety;"
Checking the correct implementation of "cmd_time"... [OK]
Checking the correct environment of "bscu1.cmd_time"... [OK]
Checking the correct environment of "bscu2.cmd_time"... [OK]
Checking the correct environment of "switch.sel0_time"... [OK]
Checking the correct environment of "switch.sel1_time"... [OK]
Checking the correct environment of "bscu1.safety"... [OK]
Checking the correct environment of "bscu2.safety"... [OK]
Checking "CONTRACT safety REFINEDBY bscu1.safety, bscu2.safety;"
Checking the correct implementation of "safety"... [OK]
Checking the correct environment of "bscu1.safety"... [OK]
Checking the correct environment of "bscu2.safety"... [OK]

Checking refinement of component: subBSCU

Checking refinement of component: Select_Switch

Checking refinement of component: Hydraulic

-------------------------------------------------------------------------------



===============================================================================
OCRA_CHECK_IMPLEMENTATION
===============================================================================
Given a finite state machine modeled in the SMV language, and an Othello System
Specification, verifies if the machine satisfies the contracts defined in the
OSS. At the moment, the command can be used only with propositional models.

Example of use:

-------------------------------------------------------------------------------

ocra > ocra_check_implementation -i WBS_propositional.oss -I WBS_Select_Switch.smv -c Select_Switch
Checking contract sel0_time ... [OK]

Checking contract sel1_time ... [OK]

-------------------------------------------------------------------------------


===============================================================================
THE MODELS
===============================================================================
A set of models are provided to show how the tool works. The example is a Wheel
Brake System. An old version of the model can be found in
https://es.fbk.eu/people/tonetta/publications/seaa12.pdf

Five models are provided in the models/wbs folder:

WBS.oss
  The Othello System Specification.

WBS_propositional.oss
  A translation of the previous model limited to propositional language.

WBS_Select_Switch.smv, WBS_Hydraulic.smv, WBS_subBSCU.smv
  The implementation of the basic components of the WBS. They can be checked
  using the command ocra_check_implementation.


===============================================================================
FOLDER CONTENT
===============================================================================
File:                     Short description:
-------------------------------------------------------------------------------
README.txt                 This document
LICENSE.txt                The terms of use
ocra_counterexample.txt    An example of a ocra counterexample

bin_linux32bit/
  ocra                     The ocra executable for Gnu/Linux 32 bit

bin_windows_32bit/
  ocra.exe                 The ocra executable for Windows 32 bit
  libgcc_s_sjlj-1.dll      The needed dlls
  libreadline6.dll
  libstdc++-6.dll

wbs/                       the set of SMV and OSS models 
  WBS.oss,                 
  WBS_propositional.oss,
  WBS_Select_Switch,
  WBS_Hydraulic,
  WBS_subBSCU
examples/                  other miscellaneous models


===============================================================================
ocra more useful interactive commands reference sheet
===============================================================================
Command:                        Action:
-------------------------------------------------------------------------------
ocra_check_syntax               check the syntax of an Othello System
                                  Specification (OSS)
ocra_check_refinement           check a OSS
ocra_check_implementation       checks the implementation of a component
                                  against its contracts
quit                            exit the interactive session

-------------------------------------------------------------------------------
Reminder: to enter an interactive session, simply call: ./ocra -int
-------------------------------------------------------------------------------
