17
17
class ssa_exprt ;
18
18
class symbol_exprt ;
19
19
20
+ // / The interface of the target _container_ for symbolic execution to record its
21
+ // / symbolic steps into. Presently, \ref symex_target_equationt is the only
22
+ // / implementation of this interface.
20
23
class symex_targett
21
24
{
22
25
public:
@@ -26,6 +29,9 @@ class symex_targett
26
29
27
30
virtual ~symex_targett () { }
28
31
32
+ // / Identifies source in the context of symbolic execution. Thread number
33
+ // / `thread_nr` is zero by default and the program counter `pc` points to the
34
+ // / first instruction of the input GOTO program.
29
35
struct sourcet
30
36
{
31
37
unsigned thread_nr;
@@ -65,21 +71,45 @@ class symex_targett
65
71
GUARD,
66
72
};
67
73
68
- // read event
74
+ // / Read from a shared variable \p ssa_object (which is both the left- and the
75
+ // / right--hand side of assignment): we effectively assign the value stored in
76
+ // / \p ssa_object by another thread to \p ssa_object in the memory scope of
77
+ // / this thread.
78
+ // / \param guard: Precondition for this read event
79
+ // / \param ssa_object: Variable to be read from
80
+ // / \param atomic_section_id: ID of the atomic section in which this read
81
+ // / takes place (if any)
82
+ // / \param source: Pointer to location in the input GOTO program of this read
69
83
virtual void shared_read (
70
84
const exprt &guard,
71
- const ssa_exprt &ssa_rhs ,
85
+ const ssa_exprt &ssa_object ,
72
86
unsigned atomic_section_id,
73
- const sourcet &source)=0;
74
-
75
- // write event
87
+ const sourcet &source) = 0;
88
+
89
+ // / Write to a shared variable \p ssa_object: we effectively assign a value
90
+ // / from this thread to be visible by other threads.
91
+ // / \param guard: Precondition for this write event
92
+ // / \param ssa_object: Variable to be written to
93
+ // / \param atomic_section_id: ID of the atomic section in which this write
94
+ // / takes place (if any)
95
+ // / \param source: Pointer to location in the input GOTO program of this write
76
96
virtual void shared_write (
77
97
const exprt &guard,
78
- const ssa_exprt &ssa_rhs ,
98
+ const ssa_exprt &ssa_object ,
79
99
unsigned atomic_section_id,
80
- const sourcet &source)=0;
81
-
82
- // write event - lhs must be symbol
100
+ const sourcet &source) = 0;
101
+
102
+ // / Write to a local variable. The `cond_expr` is _lhs==rhs_.
103
+ // / \param guard: Precondition for this read event
104
+ // / \param ssa_lhs: Variable to be written to, must be a symbol (and not nil)
105
+ // / \param ssa_full_lhs: Full left-hand side with symex level annotations
106
+ // / \param original_full_lhs: Full left-hand side without symex level
107
+ // / annotations
108
+ // / \param ssa_rhs: Right-hand side of the assignment
109
+ // / \param source: Pointer to location in the input GOTO program of this
110
+ // / assignment
111
+ // / \param assignment_type: To distinguish between different types of
112
+ // / assignments (some may be hidden for the further analysis)
83
113
virtual void assignment (
84
114
const exprt &guard,
85
115
const ssa_exprt &ssa_lhs,
@@ -89,104 +119,181 @@ class symex_targett
89
119
const sourcet &source,
90
120
assignment_typet assignment_type)=0;
91
121
92
- // declare fresh variable - lhs must be symbol
122
+ // / Declare a fresh variable. The `cond_expr` is _lhs==lhs_.
123
+ // / \param guard: Precondition for a declaration of this variable
124
+ // / \param ssa_lhs: Variable to be declared, must be symbol (and not nil)
125
+ // / \param source: Pointer to location in the input GOTO program of this
126
+ // / declaration
127
+ // / \param assignment_type: To distinguish between different types of
128
+ // / assignments (some may be hidden for the further analysis)
93
129
virtual void decl (
94
130
const exprt &guard,
95
131
const ssa_exprt &ssa_lhs,
96
132
const sourcet &source,
97
133
assignment_typet assignment_type)=0;
98
134
99
- // note the death of a variable - lhs must be symbol
135
+ // / Remove a variable from the scope.
136
+ // / \param guard: Precondition for removal of this variable
137
+ // / \param ssa_lhs: Variable to be removed, must be symbol
138
+ // / \param source: Pointer to location in the input GOTO program of this
139
+ // / removal
100
140
virtual void dead (
101
141
const exprt &guard,
102
142
const ssa_exprt &ssa_lhs,
103
143
const sourcet &source)=0;
104
144
105
- // record a function call
145
+ // / Record a function call.
146
+ // / \param guard: Precondition for calling a function
147
+ // / \param function_identifier: Name of the function
148
+ // / \param ssa_function_arguments: Vector of arguments in SSA form
149
+ // / \param source: To location in the input GOTO program of this
150
+ // / \param hidden: Should this step be recorded as hidden?
151
+ // / function call
106
152
virtual void function_call (
107
153
const exprt &guard,
108
154
const irep_idt &function_identifier,
109
155
const std::vector<exprt> &ssa_function_arguments,
110
156
const sourcet &source,
111
157
bool hidden) = 0;
112
158
113
- // record return from a function
159
+ // / Record return from a function.
160
+ // / \param guard: Precondition for returning from a function
161
+ // / \param source: Pointer to location in the input GOTO program of this
162
+ // / \param hidden: Should this step be recorded as hidden?
163
+ // / function return
114
164
virtual void
115
165
function_return (const exprt &guard, const sourcet &source, bool hidden) = 0 ;
116
166
117
- // just record a location
167
+ // / Record a location.
168
+ // / \param guard: Precondition for reaching this location
169
+ // / \param source: Pointer to location in the input GOTO program to be
170
+ // / recorded
118
171
virtual void location (
119
172
const exprt &guard,
120
173
const sourcet &source)=0;
121
174
122
- // record output
175
+ // / Record an output.
176
+ // / \param guard: Precondition for writing to the output
177
+ // / \param source: Pointer to location in the input GOTO program of this
178
+ // / output
179
+ // / \param output_id: Name of the output
180
+ // / \param args: A list of IO arguments
123
181
virtual void output (
124
182
const exprt &guard,
125
183
const sourcet &source,
126
184
const irep_idt &output_id,
127
185
const std::list<exprt> &args)=0;
128
186
129
- // record formatted output
187
+ // / Record formatted output.
188
+ // / \param guard: Precondition for writing to the output
189
+ // / \param source: Pointer to location in the input GOTO program of this
190
+ // / output
191
+ // / \param output_id: Name of the output
192
+ // / \param fmt: Formatting string
193
+ // / \param args: A list of IO arguments
130
194
virtual void output_fmt (
131
195
const exprt &guard,
132
196
const sourcet &source,
133
197
const irep_idt &output_id,
134
198
const irep_idt &fmt,
135
199
const std::list<exprt> &args)=0;
136
200
137
- // record input
201
+ // / Record an input.
202
+ // / \param guard: Precondition for reading from the input
203
+ // / \param source: Pointer to location in the input GOTO program of this
204
+ // / input
205
+ // / \param input_id: Name of the input
206
+ // / \param args: A list of IO arguments
138
207
virtual void input (
139
208
const exprt &guard,
140
209
const sourcet &source,
141
210
const irep_idt &input_id,
142
211
const std::list<exprt> &args)=0;
143
212
144
- // record an assumption
213
+ // / Record an assumption.
214
+ // / \param guard: Precondition for reaching this assumption
215
+ // / \param cond: Condition this assumption represents
216
+ // / \param source: Pointer to location in the input GOTO program of this
217
+ // / assumption
145
218
virtual void assumption (
146
219
const exprt &guard,
147
220
const exprt &cond,
148
221
const sourcet &source)=0;
149
222
150
- // record an assertion
223
+ // / Record an assertion.
224
+ // / \param guard: Precondition for reaching this assertion
225
+ // / \param cond: Condition this assertion represents
226
+ // / \param msg: The message associated with this assertion
227
+ // / \param source: Pointer to location in the input GOTO program of this
228
+ // / assertion
151
229
virtual void assertion (
152
230
const exprt &guard,
153
231
const exprt &cond,
154
232
const std::string &msg,
155
233
const sourcet &source)=0;
156
234
157
- // record a goto
235
+ // / Record a goto instruction.
236
+ // / \param guard: Precondition for reaching this goto instruction
237
+ // / \param cond: Condition under which this goto should be taken
238
+ // / \param source: Pointer to location in the input GOTO program of this
239
+ // / goto instruction
158
240
virtual void goto_instruction (
159
241
const exprt &guard,
160
242
const exprt &cond,
161
243
const sourcet &source)=0;
162
244
163
- // record a constraint
245
+ // / Record a _global_ constraint: there is no guard limiting its scope.
246
+ // / \param cond: Condition represented by this constraint
247
+ // / \param msg: The message associated with this constraint
248
+ // / \param source: Pointer to location in the input GOTO program of this
249
+ // / constraint
164
250
virtual void constraint (
165
251
const exprt &cond,
166
252
const std::string &msg,
167
253
const sourcet &source)=0;
168
254
169
- // record thread spawn
255
+ // / Record spawning a new thread
256
+ // / \param guard: Precondition for reaching spawning a new thread
257
+ // / \param source: Pointer to location in the input GOTO program where a new
258
+ // / thread is to be spawned
170
259
virtual void spawn (
171
260
const exprt &guard,
172
261
const sourcet &source)=0;
173
262
174
- // record memory barrier
263
+ // / Record creating a memory barrier
264
+ // / \param guard: Precondition for reaching this barrier
265
+ // / \param source: Pointer to location in the input GOTO program where a new
266
+ // / barrier is created
175
267
virtual void memory_barrier (
176
268
const exprt &guard,
177
269
const sourcet &source)=0;
178
270
179
- // record atomic section
271
+ // / Record a beginning of an atomic section
272
+ // / \param guard: Precondition for reaching this atomic section
273
+ // / \param atomic_section_id: Identifier for this atomic section
274
+ // / \param source: Pointer to location in the input GOTO program where an
275
+ // / atomic section begins
180
276
virtual void atomic_begin (
181
277
const exprt &guard,
182
278
unsigned atomic_section_id,
183
279
const sourcet &source)=0;
280
+
281
+ // / Record ending an atomic section
282
+ // / \param guard: Precondition for reaching the end of this atomic section
283
+ // / \param atomic_section_id: Identifier for this atomic section
284
+ // / \param source: Pointer to location in the input GOTO program where an
285
+ // / atomic section ends
184
286
virtual void atomic_end (
185
287
const exprt &guard,
186
288
unsigned atomic_section_id,
187
289
const sourcet &source)=0;
188
290
};
189
291
292
+ // / Base class comparison operator for symbolic execution targets. Order first
293
+ // / by thread numbers and then by program counters.
294
+ // / \param a: Left-hand target
295
+ // / \param b: Right-hand target
296
+ // / \return _True_ if `a` precedes `b`.
190
297
bool operator < (
191
298
const symex_targett::sourcet &a,
192
299
const symex_targett::sourcet &b);
0 commit comments