Skip to content

Commit 38c8afe

Browse files
authored
Merge pull request #3393 from xbauch/docu/symex_target
Class and function documentation for goto-symex-target [DOC-79]
2 parents 56c520b + bff5bf4 commit 38c8afe

File tree

4 files changed

+229
-79
lines changed

4 files changed

+229
-79
lines changed

src/goto-symex/goto_symex.h

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -397,6 +397,12 @@ class goto_symext
397397
guardt &,
398398
assignment_typet);
399399

400+
/// Store the \p what expression by recursively descending into the operands
401+
/// of \p lhs until the first operand \c op0 is _nil_: this _nil_ operand
402+
/// is then replaced with \p what.
403+
/// \param lhs: Non-symbol pointed-to expression
404+
/// \param what: The expression to be added to the \p lhs
405+
/// \return The resulting expression
400406
static exprt add_to_lhs(const exprt &lhs, const exprt &what);
401407

402408
virtual void symex_gcc_builtin_va_arg_next(

src/goto-symex/symex_target.h

Lines changed: 131 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,9 @@ Author: Daniel Kroening, [email protected]
1717
class ssa_exprt;
1818
class symbol_exprt;
1919

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.
2023
class symex_targett
2124
{
2225
public:
@@ -26,6 +29,9 @@ class symex_targett
2629

2730
virtual ~symex_targett() { }
2831

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.
2935
struct sourcet
3036
{
3137
unsigned thread_nr;
@@ -65,21 +71,45 @@ class symex_targett
6571
GUARD,
6672
};
6773

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
6983
virtual void shared_read(
7084
const exprt &guard,
71-
const ssa_exprt &ssa_rhs,
85+
const ssa_exprt &ssa_object,
7286
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
7696
virtual void shared_write(
7797
const exprt &guard,
78-
const ssa_exprt &ssa_rhs,
98+
const ssa_exprt &ssa_object,
7999
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)
83113
virtual void assignment(
84114
const exprt &guard,
85115
const ssa_exprt &ssa_lhs,
@@ -89,104 +119,181 @@ class symex_targett
89119
const sourcet &source,
90120
assignment_typet assignment_type)=0;
91121

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)
93129
virtual void decl(
94130
const exprt &guard,
95131
const ssa_exprt &ssa_lhs,
96132
const sourcet &source,
97133
assignment_typet assignment_type)=0;
98134

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
100140
virtual void dead(
101141
const exprt &guard,
102142
const ssa_exprt &ssa_lhs,
103143
const sourcet &source)=0;
104144

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
106152
virtual void function_call(
107153
const exprt &guard,
108154
const irep_idt &function_identifier,
109155
const std::vector<exprt> &ssa_function_arguments,
110156
const sourcet &source,
111157
bool hidden) = 0;
112158

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
114164
virtual void
115165
function_return(const exprt &guard, const sourcet &source, bool hidden) = 0;
116166

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
118171
virtual void location(
119172
const exprt &guard,
120173
const sourcet &source)=0;
121174

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
123181
virtual void output(
124182
const exprt &guard,
125183
const sourcet &source,
126184
const irep_idt &output_id,
127185
const std::list<exprt> &args)=0;
128186

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
130194
virtual void output_fmt(
131195
const exprt &guard,
132196
const sourcet &source,
133197
const irep_idt &output_id,
134198
const irep_idt &fmt,
135199
const std::list<exprt> &args)=0;
136200

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
138207
virtual void input(
139208
const exprt &guard,
140209
const sourcet &source,
141210
const irep_idt &input_id,
142211
const std::list<exprt> &args)=0;
143212

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
145218
virtual void assumption(
146219
const exprt &guard,
147220
const exprt &cond,
148221
const sourcet &source)=0;
149222

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
151229
virtual void assertion(
152230
const exprt &guard,
153231
const exprt &cond,
154232
const std::string &msg,
155233
const sourcet &source)=0;
156234

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
158240
virtual void goto_instruction(
159241
const exprt &guard,
160242
const exprt &cond,
161243
const sourcet &source)=0;
162244

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
164250
virtual void constraint(
165251
const exprt &cond,
166252
const std::string &msg,
167253
const sourcet &source)=0;
168254

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
170259
virtual void spawn(
171260
const exprt &guard,
172261
const sourcet &source)=0;
173262

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
175267
virtual void memory_barrier(
176268
const exprt &guard,
177269
const sourcet &source)=0;
178270

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
180276
virtual void atomic_begin(
181277
const exprt &guard,
182278
unsigned atomic_section_id,
183279
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
184286
virtual void atomic_end(
185287
const exprt &guard,
186288
unsigned atomic_section_id,
187289
const sourcet &source)=0;
188290
};
189291

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`.
190297
bool operator < (
191298
const symex_targett::sourcet &a,
192299
const symex_targett::sourcet &b);

0 commit comments

Comments
 (0)