0b55f123 |
1 | .ds Z S\s-2PIN\s0 |
2 | .ds P P\s-2ROMELA\s0 |
3 | .\" |
4 | .\" On CYGWIN move this page to c:/cygwin/usr/man/man1/spin.1 |
5 | .\" |
6 | .TH SPIN 1 |
7 | .CT 1 comm_mach protocol |
8 | .SH NAME |
9 | spin \(mi verification tool for models of concurrent systems |
10 | .SH SYNOPSIS |
11 | .B spin |
12 | .BI "-a [-m]" |
13 | [ |
14 | .BI -P cpp |
15 | ] |
16 | .I file |
17 | .br |
18 | .B spin |
19 | .BI "[-bglmprsv] [-n\f2N\f(BI]" |
20 | [ |
21 | .BI -P cpp |
22 | ] |
23 | .I file |
24 | .br |
25 | .B spin |
26 | .BI "-c [-t]" |
27 | [ |
28 | .BI -P cpp |
29 | ] |
30 | .I file |
31 | .br |
32 | .B spin |
33 | .BI -d |
34 | [ |
35 | .BI -P cpp |
36 | ] |
37 | .I file |
38 | .br |
39 | .B spin |
40 | .BI -f |
41 | .I LTL |
42 | .br |
43 | .B spin |
44 | .BI -F |
45 | .I file |
46 | .br |
47 | .B spin |
48 | .BI "-i [-bglmprsv] [-n\f2N\f(BI]" |
49 | [ |
50 | .BI -P cpp |
51 | ] |
52 | .I file |
53 | .br |
54 | .B spin |
55 | .BI "-M [-t]" |
56 | [ |
57 | .BI -P cpp |
58 | ] |
59 | .I file |
60 | .br |
61 | .B spin |
62 | .BI "-t[N] [-bglmprsv] [-j\f2N\f(BI]" |
63 | [ |
64 | .BI -P cpp |
65 | ] |
66 | .I file |
67 | .br |
68 | .B spin |
69 | .BI -V |
70 | .I file |
71 | .SH DESCRIPTION |
72 | \*Z |
73 | is a tool for analyzing the logical consistency of |
74 | asynchronous systems, specifically distributed software |
75 | amd communication protocols. |
76 | A verification model of the system is first specified |
77 | in a guarded command language called Promela. |
78 | This specification language, described in the reference, |
79 | allows for the modeling of dynamic creation of |
80 | asynchronous processes, |
81 | nondeterministic case selection, loops, gotos, local and |
82 | global variables. |
83 | It also allows for a concise specification of logical |
84 | correctness requirements, including, but not restricted |
85 | to requirements expressed in linear temporal logic. |
86 | .PP |
87 | Given a Promela model |
88 | stored in |
89 | .I file , |
90 | \*Z can perform interactive, guided, or random simulations |
91 | of the system's execution. |
92 | It can also generate a C program that performs an exhaustive |
93 | or approximate verification of the correctness requirements |
94 | for the system. |
95 | .\"----------------------a---------------- |
96 | .TP |
97 | .B -a |
98 | Generate a verifier (model checker) for the specification. |
99 | The output is written into a set of C files, named |
100 | .BR pan. [ cbhmt ], |
101 | that can be compiled |
102 | .RB ( "cc pan.c" ) |
103 | to produce an executable verifier. |
104 | The online \*Z manuals (see below) contain |
105 | the details on compilation and use of the verifiers. |
106 | .\"--------------------------c------------ |
107 | .TP |
108 | .B -c |
109 | Produce an ASCII approximation of a message sequence |
110 | chart for a random or guided \19(when combined with \f3-t\f1) |
111 | simulation run. See also option \f3-M\f1. |
112 | .\"--------------------------d------------ |
113 | .TP |
114 | .BI -d |
115 | Produce symbol table information for the model specified in |
116 | .I file . |
117 | For each Promela object this information includes the type, name and |
118 | number of elements (if declared as an array), the initial |
119 | value (if a data object) or size (if a message channel), the |
120 | scope (global or local), and whether the object is declared as |
121 | a variable or as a parameter. For message channels, the data types |
122 | of the message fields are listed. |
123 | For structure variables, the 3rd field defines the |
124 | name of the structure declaration that contains the variable. |
125 | .\"--------------------------f------------ |
126 | .TP |
127 | .BI "-f \f2LTL\f1" |
128 | Translate the LTL formula \f2LTL\f1 into a never claim. |
129 | .br |
130 | This option reads a formula in LTL syntax from the second argument |
131 | and translates it into Promela syntax (a never claim, qhich is Promela's |
132 | equivalent of a B\(u"chi Automaton). |
133 | The LTL operators are written: [] (always), <> (eventually), |
134 | and U (strong until). There is no X (next) operator, to secure |
135 | compatibility with the partial order reduction rules that are |
136 | applied during the verification process. |
137 | If the formula contains spaces, it should be quoted to form a |
138 | single argument to the \*Z command. |
139 | .\"--------------------------F------------ |
140 | .TP |
141 | .BI "-F \f2file\f1" |
142 | Translate the LTL formula stored in |
143 | .I file |
144 | into a never claim. |
145 | .br |
146 | This behaves identical to option |
147 | .B -f |
148 | but will read the formula from the |
149 | .I file |
150 | instead of from the command line. |
151 | The file should contain the formula as the first line. Any text |
152 | that follows this first line is ignored, so it can be used to |
153 | store comments or annotation on the formula. |
154 | (On some systems the quoting conventions of the shell complicate |
155 | the use of option |
156 | .B -f . |
157 | Option |
158 | .B -F |
159 | is meant to solve those problems.) |
160 | .\"--------------------------i------------ |
161 | .TP |
162 | .BI -i |
163 | Perform an interactive simulation, prompting the user at |
164 | every execution step that requires a nondeterministic choice |
165 | to be made. The simulation proceeds without user intervention |
166 | when execution is deterministic. |
167 | .\"--------------------------M------------ |
168 | .TP |
169 | .BI -M |
170 | Produce a message sequence chart in Postscript form for a |
171 | random simulation or a guided simulation |
172 | (when combined with \f(BI-t\f1), for the model in |
173 | .I file , |
174 | and write the result into |
175 | .I file.ps . |
176 | See also option \f3-c\f1. |
177 | .\"--------------------------m------------ |
178 | .TP |
179 | .BI -m |
180 | Changes the semantics of send events. |
181 | Ordinarily, a send action will be (blocked) if the |
182 | target message buffer is full. |
183 | With this option a message sent to a full buffer is lost. |
184 | .\"--------------------------n------------ |
185 | .TP |
186 | .BI "-n\f2N" |
187 | Set the seed for a random simulation to the integer value |
188 | .I N . |
189 | There is no space between the \f(BI-n\f1 and the integer \f2N\f1. |
190 | .\"--------------------------t------------ |
191 | .TP |
192 | .BI -t |
193 | Perform a guided simulation, following the error trail that |
194 | was produces by an earlier verification run, see the online manuals |
195 | for the details on verification. |
196 | .\"--------------------------V------------ |
197 | .TP |
198 | .BI -V |
199 | Prints the \*Z version number and exits. |
200 | .\"--------------------------.------------ |
201 | .PP |
202 | With only a filename as an argument and no option flags, |
203 | \*Z performs a random simulation of the model specified in |
204 | the file (standard input is the default if the filename is omitted). |
205 | This normally does not generate output, except what is generated |
206 | explicitly by the user within the model with \f(CWprintf\f1 |
207 | statements, and some details about the final state that is |
208 | reached after the simulation completes. |
209 | The group of options |
210 | .B -bglmprsv |
211 | is used to set the desired level of information that the user wants |
212 | about a random, guided, or interactive simulation run. |
213 | Every line of output normally contains a reference to the source |
214 | line in the specification that generated it. |
215 | If option |
216 | .B -i |
217 | is added, the simulation is \f2interactive\f1, or if option |
218 | .B -t |
219 | is added, the simulation is \f2guided\f1. |
220 | .\"--------------------------bglprsv------------ |
221 | .TP |
222 | .BI -b |
223 | Suppress the execution of \f(CWprintf\f1 statements within the model. |
224 | .TP |
225 | .BI -g |
226 | Show at each time step the current value of global variables. |
227 | .TP |
228 | .BI -l |
229 | In combination with option |
230 | .BR -p , |
231 | show the current value of local variables of the process. |
232 | .TP |
233 | .BI -p |
234 | Show at each simulation step which process changed state, |
235 | and what source statement was executed. |
236 | .TP |
237 | .BI -r |
238 | Show all message-receive events, giving |
239 | the name and number of the receiving process |
240 | and the corresponding the source line number. |
241 | For each message parameter, show |
242 | the message type and the message channel number and name. |
243 | .TP |
244 | .BI -s |
245 | Show all message-send events. |
246 | .TP |
247 | .BI -v |
248 | Verbose mode, add some more detail, and generat more |
249 | hints and warnings about the model. |
250 | .SH SEE ALSO |
251 | Online manuals at spinroot.com: |
252 | .br |
253 | .in +4 |
254 | GettingStarted.pdf, |
255 | Roadmap.pdf, |
256 | Manual.pdf, |
257 | WhatsNew.pdf, |
258 | Exercises.pdf |
259 | .in -4 |
260 | More background information on the system and the verification process, |
261 | can be found in, for instance: |
262 | .br |
263 | .in +4 |
264 | G.J. Holzmann, \f2Design and Validation of Computer Protocols\f1, |
265 | Prentice Hall, 1991. |
266 | .br |
267 | --, `Design and validation of protocols: a tutorial,' |
268 | \f2Computer Networks and ISDN Systems\f1, |
269 | Vol. 25, No. 9, 1993, pp. 981-1017. |
270 | .br |
271 | --, `The model checker \*Z,' |
272 | \f2IEEE Trans. on SE\f1, Vol, 23, No. 5, May 1997. |
273 | .in -4 |
274 | .br |