Spin - Version 3.0.6 - December 1997

`SPIN README`

General Description of Spin
Downloading and Installation
- Unix systems
- Windows95/WindowsNT PC's
Related software (gcc, tcl/tk)
Updates of the Spin sources
Spin documentation
Theoretical Background
Mailing List
Spin Workshops

`1. General Description`

Spin is an efficient on-the-fly verification system (a `model checker') for asynchronous concurrent systems, such as data communication protocols, distributed operating systems, database systems, etc. It can be used to prove both safety and liveness properties, including all correctness requirements expressible in linear time temporal logic.

Spin supports dynamically growing and shrinking numbers of asynchronous processes, supports both rendezvous and buffered message passing, and communication through shared memory.

The Spin software is distributed through the netlib server. All files can be found on the host netlib.bell-labs.com in directory /netlib/spin -- or via the following URLs:

	http://netlib.bell-labs.com/netlib/spin/index.html
	http://netlib.bell-labs.com/netlib/spin/whatispin.html

The software includes a random simulator, interactive and guided simulation options, and formal verification based on either exhaustive or reduced reachability analysis. The software contains efficient implementations of partial order reduction techniques, and (as an option) the supertrace storage technique to handle very large verification problems.

Included is also an X-windows interface to the Spin system, called 'xspin', written in Tcl/Tk.

There are many thousands of installations of the Spin software. The mailing list information at the end of this file contains information about the newsletter and annual workshops.

`2. Downloading Spin`

The current version is Spin 3.0, which runs on any Unix workstation or mainframe, as well as on PCs under Windows95 or WindowsNT. To get up and running with Spin from scratch you will need to download the following compressed tar-files.

On UNIX systems, directly compile Spin from the: C-sources + Xspin, docs, and examples
For installation notes see 2a below.
On Windows95/WindowsNT PCs: 32-bit precompiled Spin + Xspin, and examples
For installation notes see 2b below.

`2a. Installation Notes for Unix Systems`

Installing Spin (Unix)

First cd to Src directory from this distribution and type `make'.

Spin should compile without warnings. You do not have to do anything special unless you are on a Solaris system or a PC (in that case, read the comments in the makefile first). Install the executable version of spin in a directory that is within your default search path (such as your home bin directory, or /usr/local/bin etc.)

You may have to adapt the makefile to pick up an ANSI C standard C compiler (for instance, the Gnu C compiler, gcc). (If you need to install gcc, yacc, or Tcl/Tk, see below under: Related Software)

If all else fails, you can also compile everything with the following two lines:

	yacc -v -d spin.y
	cc -o spin *.c

Spin assumes that the standard C preprocessor cpp is stored in file "/lib/cpp". On some systems this is different. On a Solaris system, for instance, the file is "/usr/ccs/lib/cpp". You can define this by adding the compiler directive

	 -DSOLARIS

in the makefile.

To test the basic sanity of the Spin executable, do:

	$ cd Test
	$ spin -V
	Spin Version 2.9.0 -- 14 July 1995
	$ spin hello
	passed first test!
	1 processes created
	$ spin -a loops
	$ cc -o pan pan.c	# or: gcc -ansi -o pan pan.c
	$ pan
	(Spin Version 2.9.0 -- 14 July 1995)
	...no errors, check:
	      17 states, stored
	       5 states, matched
	      22 transitions (= stored+matched)
	       0 atomic steps
	...
	$ pan -a
	...1 error, check:
	      14 states, stored (16 visited)
	       2 states, matched
	      18 transitions (= visited+matched)
	       0 atomic steps
	...
	$ cc -DNP -o pan pan.c	# non-progress cycle detection
	$ pan -l
	...no errors, check:
	      30 states, stored (43 visited)
	      35 states, matched
	      78 transitions (= visited+matched)
	       0 atomic steps
	$ spin -t -p loops
	...prints error-trace from pan -a above
	$ rm -f pan*  loops.trail	# clean up debris from tests

Installing Xspin (Unix)

Xspin is a graphical interface to Spin, written in Tcl/Tk, that can greatly simplify running simulations and verifications. The current version of Xspin requires access to Spin version 3.0 or later. You can find out which version of Spin you have by typing:

	$ spin -V

(Very old versions of Spin do not recognize this option.)

To obtain Tcl/Tk, see 'related software' below.

The current version of Xspin is compatible with

	Tk version 4.2 - Tcl version 7.6

and should be compatible with also some earlier versions of Tcl/Tk. It has also been tested with the 8.01b beta release of

	Tk version 8.0 - Tcl version 8.0

and appears to be working well.

Xspin 3.0 prints the version numbers of Spin, Xspin, and Tcl/Tk when it starts up. You can also check separately which version of Tcl/Tk you have installed by executing the following commands in `wish' (a Tcl/Tk command):

	info tclversion
	puts $tk_version

Unlike earlier versions of Xspin, all source is now collected into a single file inside the Xspin directory to simplify installation.

Xspin can also make use the graph layout program 'dot' if it is available on your system (not required, but nice if it's there -- xspin will automatically recognize if 'dot' is installed.) For information on 'dot,' see also 'related software.'

To install Xspin on Unix, cd to directory Xspin,

(a) change the 1st line of the xspin script to point to the executable `wish' command on your system that you want to use. make sure this pathname (it must be a full path) is less than 30 characters long
(b) copy the file into a directory within your search path and make it executable, for instance:
```
	cp xspin* /usr/local/bin/xspin
	chmod +x /usr/local/bin/xspin
```
(c) make sure that an executable version of `spin' itself is also within your search path, and is up to date.
(d) if you use `gcc' instead of `cc' to compile `spin' you should use `gcc' with xspin as well. do so at the start of the file xspin* -- the correct place is indicated at the start (it's an editable script file)

On Unix, invoke the program by typing

	xspin

	xspin promela_spec

For example:

	xspin Test/leader

Check the online Help menus in xspin for more details on routine use.

`2b. Installation Notes for PC's (Windows95 and WindowsNT)`

Installing Spin (Windows95/WindowsNT)

Install the precompiled executable of Spin that sits in the pc*.zip file in the Spin distribution. Unzip the file, and copy spin.exe into a directory with executables that is in your search path.

If you want to compile Spin from its sources for the PC, you will need a version of 'yacc,' plus the normal c-compiler. (See related software on where to get public versions.) A c-compiler and c-preprocessor will be needed in either case to be able to run verifications though, so it is wise to make sure these are installed before you try running Spin.

Install all of: gcc.exe, cpp.exe, go32.exe, and spin.exe in the gcc\bin directory, which should be part of the search path you setup in the autoexec.bat file on your PC (as per the instructions from the gcc readme.1st file). In any case, do not keep spin.exe in the same directory as the Promela files you'll be working on.

Installing Xspin (Windows95/WindowsNT)

The xspin source is in the .zip file of the distribution. You may want to rename it into 'xspin.tcl' and copy it into, or near, a directory where you plan to work, or put a shortcut to this file in the Start Menu or on the Desktop.

To run Xspin, you need the PC version of Tcl/Tk (see related software.) Note: Tcl/Tk is works on Windows95 or WindowsNT, but not on Windows 3.1.

The easiest way to start Xspin is to name it

	xspin.tcl

and double-click it (perhaps telling Windows once that files with the .tcl extension are meant to be opened by 'wish')

Another way to force xspin to startup is to first start `wish' from the Start Menu, under Programs, then to select the larger window that comes up (the command window), and to cd to the directory where you've stored the XSpin file. Then you can start it up by typing:

	source xspin.tcl	# or whatever else you've named this

and you should be up and running.

Be careful: don't store the executable for spin itself (spin.exe) in the same directory as the tcl/tk source for xspin -- for some reason wish does not call spin.exe correctly in that case. Place spin.exe in a directory with executables within your search path (e.g., in gcc\bin where gcc.exe also lives).

The PC installation assumes that you have a command called "cpp.exe" available (which comes with the gnu-c installation), which is the traditional name of the C preprocessor. To complicate your life somewhat, if you have a copy of the Borland C++ compiler installed, you'll notice that this cplusplus compiler was also named cpp.exe -- that's not the cpp you want of course. To avoid the name clash, you either have to edit the Spin source code to give it the full path name of the 'real' cpp.exe and recompile, or use Spin with the command-line option -Pxxxx where xxxx is the path for cpp.exe. Nothing much in Spin will work without access to cpp.exe. You can however do a lot without gcc.exe. The latter is required only for verifications and for the FSM views in Xspin.

`3. Related Software`

GCC

A public domain version of the gcc binaries for PCs is available at:

	http://www.simtel.net/simtel.net/

To determine the name of the files to download for the gcc binaries read the following file, at the same site:

	http://www.simtel.net/pub/simtelnet/gnu/djgpp/v2/readme.1st

To run Spin on a PC you need at least the executables:

	gcc.exe, cpp.exe, and the 32bit extender go32.exe

Rename 'go32-v2.exe' from the gcc distribution to 'go32.exe' and make sure all executables are available in your search path. You also need the standard C library header files. All the above should be in the following three zip files at the site above:

	from:	/pub/simtelnet/gnu/djgpp/
	file:	v2/djdev201.zip
	file:	v2gnu/gcc2721b.zip
	file:	v2gnu/bnu27b.zip

TCL/TK Wish

Tcl/Tk was written by John Ousterhout (john.ousterhout@eng.sun.com) and is public domain. It can be obtained (for PCs or Unix) via anonymous ftp from the system

	ftp.smli.com

in directory

	/pub/tcl

or via URL

  	http://sunscript.sun.com/

more information can also be found in netnews-group: comp.lang.tcl

YACC (optional)

A public domain version of yacc for a PC can be obtained from:

	ftp.cs.berkeley.edu
	file: ~ftp/ucb/4bsd/byacc.tar.Z

(You don't need yacc on the PC's if you use the pre-compiled version of Spin for the pc in the pc*.zip file from the distribution)

DOT (optional)

Dot is a graph layout tool developed by Stephen North and colleagues at AT&T. Xspin can make use of Dot to beautify the layout of the state-machines in the FSM-view option. To obtain Dot, see the url

	http://www.research.att.com/sw/tools/graphviz/

(or if this fails, check with north@research.att.com) The basic version of Dot is for Unix systems; there are also local ports to PCs, but it is uncertain if any of these are in the public domain. For documentation of Dot see:

	A Technique for Drawing Directed Graphs,
	by Gansner, Koutsofios, North and Vo,
	IEEE-TSE, March, 1993.

`4. Updates of the Spin Sources`

Spin will continue to evolve. All changes are made available in the compressed tar file, which will always contain a full copy of the most recent version of all sources. To avoid having to reload and reinstall the full tar-file for each update, there is also a shell-script called `upgradeSrc' that can be executed in an existing Spin Src directory to apply all changes to the sources. This is safe to do even if your sources happen already to be up to date, and independent of the particular version of Spin that you have, provided you have Spin version 2.7 or later. Each modification of the sources is described in the file Doc/V[123].Updates.

`5. Spin Documentation`

- A standard manual page for Spin can be found in:
```
	Spin.html, and
	Pan.html.
```
- Online references are at:
```
	Online ManPages
```
- Basic manuals are included in:
```
	Manual.html		(language and tool)
	Quick.html		(by Rob Gerth, Eindhoven Univ./Intel)
```
Additional information can be found in the files
```
	GettingStarted.html	(mostly on xspin)
	Roadmap.html		(mostly on spin)
	WhatsNew.html		(mostly on promela)
   	Exercises.html		(routine use)
```
Some of the documentation assumes that you only have access to vanilla spin, if you have Xspin working, start with GettingStarted If you have only plain spin working, start with Roadmap and Exercises and in both cases proceed with Manual and then (later) WhatsNew.html

- For a quick introduction to Spin, a tutorial can be found in: Design and Validation of Computer Protocols, a Tutorial, Computer Networks, Vol 25, No. 9, Apr. 1993, pp. 981-1017. An overview paper appeared in: The Spin Model Checker, IEEE Trans. on Software Eng. Vol. 23, No. 5, May 1997, pp. 279-295.

- A detailed description of the software and its applications (the main Spin documentation) can be found in: Design and Validation of Computer Protocols, Gerard J. Holzmann, Prentice Hall, 1991, ISBN 0-13-539925-4. The book contents is available online in Acrobat PDF format, and in standard Postscript format. There is also a Japanese translation of the book. Included in the Spin sources distribution tar-file (see 2. above): Errata on the printed version are in: Doc/Book.Errata Answers to selected exercises: Doc/Book.answers More explanation on chapter 6 is in: Doc/Book.Ch6.add Spin examples used in the book are in: Doc/Book.samples other examples, not in the book, can be found in the Test/ directory from the distribution.

6. Theoretical Background The Automata-theoretic foundation for Spin: An automata-theoretic approach to automatic program verification, by Moshe Y. Vardi, and Pierre Wolper, Proc. First IEEE Symp. on Logic in Computer Science, 1986, pp. 322-331. The algorithm for bitstate hashing (optional in Spin for verifying large problem sizes) is discussed in detail in: An analysis of bitstate hashing, by G.J. Holzmann, Proc. PSTV 1995 Conference, Warsaw, Poland. (gzipped postscript) The algorithm for partial order reduction is described in: An Improvement in Formal Verification, by G.J. Holzmann and D. Peled, Proc. FORTE 1994 Conference, Bern, Switzerland. (gzipped postscript) The algorithm for conversion of LTL to Buchi Automata (in Spin terminology: never claims) is described in: Simple on-the-fly automatic verification of linear temporal logic, by Rob Gerth, Doron Peled, Moshe Vardi, and Pierre Wolper, Proc. PSTV 1995 Conference, Warsaw, Poland. The algorithm for storing reachable states with a minimized automaton (new in Spin Version 3.0) A Minimized automaton representation of reachable states, by A. Puri and G.J. Holzmann (to be published). 7. Mailing List Starting with Spin version 2.0 (January 1995) a mailing list of Spin users is being maintained. New releases of the Spin software are announced through the newsletters that are sent to this list. These updates also occassionally include answers to frequently asked questions, describe main new applications or projects with Spin, and serves to establish contacts between people using the Spin software in different countries (there are users in 34 different countries). To get on the list, email a one line message: "subscribe to Spin list" to spin_list@research.bell-labs.com and you will be kept up to date. Anyone who wants to announce an extension of the basic Spin software, to seek advice from or contacts with other Spin users, to make available postscript versions of papers on Spin usage (e.g. by anonymous ftp or as a URL on the internet) for feedback or communication, can also submit such items for inclusion in announcements to the mailing list. All previously issued Spin News letters are also available via the web. 8. SPIN Workshops The fourth Spin workshop is tentatively scheduled for Oct.98 in Paris. Online proceedings for the previous workshops can be found online in: http://netlib.bell-labs.com/netlib/spin/XXX/papers.html with XXX equal to ws95, ws96, or ws97 Spin HomePage (Page Updated: 16 December 1997)