Skip to content

Commit 3844b18

Browse files
Charliemowoodpeterschrammel
Charliemowood
authored and
peterschrammel
committed
Assign every module a README.md
Add doxygen layout to make change modules in toc to directories Put all modules in the directories folder by specifying the correct doxygen command
1 parent 6cb870a commit 3844b18

File tree

43 files changed

+735
-206
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+735
-206
lines changed

‎doc/architectural/cprover-architecture-overview.md‎

Lines changed: 45 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
\ingroup module_hidden
1+
\ingroup module_hidden
22
\page cprover-architecture-overview CProver Architecture Overview
33

44
\author Martin Brain, Peter Schrammel
@@ -98,7 +98,7 @@ internals of the system and how to get started on development.
9898

9999
## Documentation
100100

101-
Apart from the (user-orientated) CPROVER manual and this document, most
101+
Apart from the (user-orientated) CBMC user manual and this document, most
102102
of the rest of the documentation is inline in the code as `doxygen` and
103103
some comments. A man page for CBMC, goto-cc and goto-instrument is
104104
contained in the `doc/` directory and gives some options for these
@@ -107,6 +107,48 @@ some cases the algorithms used are described in the relevant papers.
107107

108108
## Architecture
109109

110+
This section provides a graphical overview of how CBMC fits together.
111+
CBMC takes C code or a goto-binary as input and tries to emit traces
112+
of executions that lead to crashes or undefined behaviour. The diagram
113+
below shows the intermediate steps in this process.
114+
115+
\dot
116+
digraph G {
117+
118+
rankdir="TB";
119+
node [shape=box, fontcolor=blue];
120+
121+
subgraph top {
122+
rank=same;
123+
1 -> 2 -> 3 -> 4;
124+
}
125+
126+
subgraph bottom {
127+
rank=same;
128+
5 -> 6 -> 7 -> 8 -> 9;
129+
}
130+
131+
/* shift bottom subgraph over */
132+
9 -> 1 [color=white];
133+
134+
4 -> 5;
135+
136+
1 [label="command line\nparsing" URL="\ref cbmc_parse_optionst"];
137+
2 [label="preprocessing,\nparsing" URL="\ref preprocessing"];
138+
3 [label="language\ntype-checking" URL="\ref type-checking"];
139+
4 [label="goto\nconversion" URL="\ref goto-conversion"];
140+
5 [label="instrumentation" URL="\ref instrumentation"];
141+
6 [label="symbolic\nexecution" URL="\ref symbolic-execution"];
142+
7 [label="SAT/SMT\nencoding" URL="\ref sat-smt-encoding"];
143+
8 [label="decision\nprocedure" URL="\ref decision-procedure"];
144+
9 [label="counter example\nproduction" URL="\ref counter-example-production"];
145+
}
146+
\enddot
147+
148+
The \ref cbmc-user-manual "CBMC User Manual" describes CBMC from a user
149+
perspective. Each node in the diagram above links to the appropriate
150+
class or module documentation, describing that particular stage in the
151+
CBMC pipeline.
110152
CPROVER is structured in a similar fashion to a compiler. It has
111153
language specific front-ends which perform limited syntactic analysis
112154
and then convert to an intermediate format. The intermediate format can
@@ -135,7 +177,7 @@ and doxygen comments are enforced by CI before a patch can be
135177
merged by running `clang-format` and `cpplint`.
136178

137179
Identifiers should be lower case with underscores to separate words.
138-
Types (classes, structures and typedefs) names must[^1] end with a `t`.
180+
Types (classes, structures and typedefs) names must end with a `t`.
139181
Types that model types (i.e. C types in the program that is being
140182
interpreted) are named with `_typet`. For example `ui_message_handlert`
141183
rather than `UI_message_handlert` or `UIMessageHandler` and

‎doc/architectural/howto.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
\ingroup module_hidden
12
\page tutorial Tutorials
23

34
\section cbmc_tutorial CBMC Developer Tutorial

‎src/DoxygenLayout.xml‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
<doxygenlayout version="1.0">
2+
<!-- Generated by doxygen 1.8.15 -->
3+
<!-- Navigation index tabs for HTML output -->
4+
<navindex>
5+
<tab type="mainpage" visible="yes" title=""/>
6+
<tab type="pages" visible="yes" title="" intro=""/>
7+
<tab type="modules" visible="yes" title="Directories" intro=""/>
8+
<tab type="namespaces" visible="yes" title="">
9+
<tab type="namespacelist" visible="yes" title="" intro=""/>
10+
<tab type="namespacemembers" visible="yes" title="" intro=""/>
11+
</tab>
12+
<tab type="classes" visible="yes" title="">
13+
<tab type="classlist" visible="yes" title="" intro=""/>
14+
<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
15+
<tab type="hierarchy" visible="yes" title="" intro=""/>
16+
<tab type="classmembers" visible="yes" title="" intro=""/>
17+
</tab>
18+
<tab type="files" visible="yes" title="">
19+
<tab type="filelist" visible="yes" title="" intro=""/>
20+
<tab type="globals" visible="yes" title="" intro=""/>
21+
</tab>
22+
<tab type="examples" visible="yes" title="" intro=""/>
23+
</navindex>
24+
25+
<!-- Layout definition for a class page -->
26+
<class>
27+
<briefdescription visible="yes"/>
28+
<includes visible="$SHOW_INCLUDE_FILES"/>
29+
<inheritancegraph visible="$CLASS_GRAPH"/>
30+
<collaborationgraph visible="$COLLABORATION_GRAPH"/>
31+
<memberdecl>
32+
<nestedclasses visible="yes" title=""/>
33+
<publictypes title=""/>
34+
<services title=""/>
35+
<interfaces title=""/>
36+
<publicslots title=""/>
37+
<signals title=""/>
38+
<publicmethods title=""/>
39+
<publicstaticmethods title=""/>
40+
<publicattributes title=""/>
41+
<publicstaticattributes title=""/>
42+
<protectedtypes title=""/>
43+
<protectedslots title=""/>
44+
<protectedmethods title=""/>
45+
<protectedstaticmethods title=""/>
46+
<protectedattributes title=""/>
47+
<protectedstaticattributes title=""/>
48+
<packagetypes title=""/>
49+
<packagemethods title=""/>
50+
<packagestaticmethods title=""/>
51+
<packageattributes title=""/>
52+
<packagestaticattributes title=""/>
53+
<properties title=""/>
54+
<events title=""/>
55+
<privatetypes title=""/>
56+
<privateslots title=""/>
57+
<privatemethods title=""/>
58+
<privatestaticmethods title=""/>
59+
<privateattributes title=""/>
60+
<privatestaticattributes title=""/>
61+
<friends title=""/>
62+
<related title="" subtitle=""/>
63+
<membergroups visible="yes"/>
64+
</memberdecl>
65+
<detaileddescription title=""/>
66+
<memberdef>
67+
<inlineclasses title=""/>
68+
<typedefs title=""/>
69+
<enums title=""/>
70+
<services title=""/>
71+
<interfaces title=""/>
72+
<constructors title=""/>
73+
<functions title=""/>
74+
<related title=""/>
75+
<variables title=""/>
76+
<properties title=""/>
77+
<events title=""/>
78+
</memberdef>
79+
<allmemberslink visible="yes"/>
80+
<usedfiles visible="$SHOW_USED_FILES"/>
81+
<authorsection visible="yes"/>
82+
</class>
83+
84+
<!-- Layout definition for a namespace page -->
85+
<namespace>
86+
<briefdescription visible="yes"/>
87+
<memberdecl>
88+
<nestednamespaces visible="yes" title=""/>
89+
<constantgroups visible="yes" title=""/>
90+
<classes visible="yes" title=""/>
91+
<typedefs title=""/>
92+
<enums title=""/>
93+
<functions title=""/>
94+
<variables title=""/>
95+
<membergroups visible="yes"/>
96+
</memberdecl>
97+
<detaileddescription title=""/>
98+
<memberdef>
99+
<inlineclasses title=""/>
100+
<typedefs title=""/>
101+
<enums title=""/>
102+
<functions title=""/>
103+
<variables title=""/>
104+
</memberdef>
105+
<authorsection visible="yes"/>
106+
</namespace>
107+
108+
<!-- Layout definition for a file page -->
109+
<file>
110+
<briefdescription visible="yes"/>
111+
<includes visible="$SHOW_INCLUDE_FILES"/>
112+
<includegraph visible="$INCLUDE_GRAPH"/>
113+
<includedbygraph visible="$INCLUDED_BY_GRAPH"/>
114+
<sourcelink visible="yes"/>
115+
<memberdecl>
116+
<classes visible="yes" title=""/>
117+
<namespaces visible="yes" title=""/>
118+
<constantgroups visible="yes" title=""/>
119+
<defines title=""/>
120+
<typedefs title=""/>
121+
<enums title=""/>
122+
<functions title=""/>
123+
<variables title=""/>
124+
<membergroups visible="yes"/>
125+
</memberdecl>
126+
<detaileddescription title=""/>
127+
<memberdef>
128+
<inlineclasses title=""/>
129+
<defines title=""/>
130+
<typedefs title=""/>
131+
<enums title=""/>
132+
<functions title=""/>
133+
<variables title=""/>
134+
</memberdef>
135+
<authorsection/>
136+
</file>
137+
138+
<!-- Layout definition for a group page -->
139+
<group>
140+
<briefdescription visible="yes"/>
141+
<groupgraph visible="$GROUP_GRAPHS"/>
142+
<memberdecl>
143+
<nestedgroups visible="yes" title=""/>
144+
<dirs visible="yes" title=""/>
145+
<files visible="yes" title=""/>
146+
<namespaces visible="yes" title=""/>
147+
<classes visible="yes" title=""/>
148+
<defines title=""/>
149+
<typedefs title=""/>
150+
<enums title=""/>
151+
<enumvalues title=""/>
152+
<functions title=""/>
153+
<variables title=""/>
154+
<signals title=""/>
155+
<publicslots title=""/>
156+
<protectedslots title=""/>
157+
<privateslots title=""/>
158+
<events title=""/>
159+
<properties title=""/>
160+
<friends title=""/>
161+
<membergroups visible="yes"/>
162+
</memberdecl>
163+
<detaileddescription title=""/>
164+
<memberdef>
165+
<pagedocs/>
166+
<inlineclasses title=""/>
167+
<defines title=""/>
168+
<typedefs title=""/>
169+
<enums title=""/>
170+
<enumvalues title=""/>
171+
<functions title=""/>
172+
<variables title=""/>
173+
<signals title=""/>
174+
<publicslots title=""/>
175+
<protectedslots title=""/>
176+
<privateslots title=""/>
177+
<events title=""/>
178+
<properties title=""/>
179+
<friends title=""/>
180+
</memberdef>
181+
<authorsection visible="yes"/>
182+
</group>
183+
184+
<!-- Layout definition for a directory page -->
185+
<directory>
186+
<briefdescription visible="yes"/>
187+
<directorygraph visible="yes"/>
188+
<memberdecl>
189+
<dirs visible="yes"/>
190+
<files visible="yes"/>
191+
</memberdecl>
192+
<detaileddescription title=""/>
193+
</directory>
194+
</doxygenlayout>

‎src/Makefile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,4 +107,7 @@ ipasir-build: ipasir-download
107107
$(MAKE) -C ../ipasir/sat/picosat961 libipasirpicosat961.a
108108
@(cd ../ipasir; ln -sf sat/picosat961/libipasirpicosat961.a libipasir.a)
109109

110+
doc :
111+
doxygen
112+
110113
.PHONY: ipasir-build minisat2-download glucose-download cprover-jar-build

‎src/analyses/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
1+
\ingroup module_hidden
12
\defgroup analyses analyses
3+
24
# Folder analyses
35

6+
This contains the abstract interpretation framework `ai.h` and several
7+
static analyses that instantiate it.
8+
49
FIXME: put here a good introduction describing what is contained
510
in this folder.

‎src/ansi-c/README‎

Lines changed: 0 additions & 22 deletions
This file was deleted.

‎src/ansi-c/module.md‎ renamed to ‎src/ansi-c/README.md‎

Lines changed: 46 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,27 @@
1+
\ingroup module_hidden
12
\defgroup ansi-c ansi-c
23
# Folder ansi-c
34

4-
\author Kareem Khazem
5+
\author Kareem Khazem, Martin Brain
6+
7+
\section overview Overview
8+
9+
Contains the front-end for ANSI C, plus a variety of common extensions.
10+
This parses the file, performs some basic sanity checks (this is one
11+
area in which the UI could be improved; patches most welcome) and then
12+
produces a goto-program (see below). The parser is a traditional Flex /
13+
Bison system.
14+
15+
`internal_addition.c` contains the implementation of various ‘magic’
16+
functions that are that allow control of the analysis from the source
17+
code level. These include assertions, assumptions, atomic blocks, memory
18+
fences and rounding modes.
19+
20+
The `library/` subdirectory contains versions of some of the C standard
21+
header files that make use of the CPROVER built-in functions. This
22+
allows CPROVER programs to be ‘aware’ of the functionality and model it
23+
correctly. Examples include `stdio.c`, `string.c`, `setjmp.c` and
24+
various threading interfaces.
525

626
\section preprocessing Preprocessing & Parsing
727

@@ -24,8 +44,6 @@ digraph G {
2444
\enddot
2545

2646

27-
28-
---
2947
\section type-checking Type-checking
3048

3149
In the \ref ansi-c and \ref java_bytecode directories.
@@ -112,3 +130,28 @@ called symbols. Thus, for example:
112130
parameter and return types of the function. The value of the symbol is
113131
the function's body (a \ref codet), and the symbol is stored in the
114132
symbol table with `foo` as the key.
133+
134+
135+
\section performance Parsing performance considerations
136+
137+
* Measured on trunk/regression/ansi-c/windows_h_VS_2012/main.i
138+
139+
* 13%: Copying into i_preprocessed
140+
141+
* 5%: ansi_c_parser.read()
142+
143+
* 53%: yyansi_clex()
144+
145+
* 29%: parser (without typechecking)
146+
147+
\section references Compiler References
148+
149+
CodeWarrior C Compilers Reference 3.2:
150+
151+
http://cache.freescale.com/files/soft_dev_tools/doc/ref_manual/CCOMPILERRM.pdf
152+
153+
http://cache.freescale.com/files/soft_dev_tools/doc/ref_manual/ASMX86RM.pdf
154+
155+
ARM 4.1 Compiler Reference:
156+
157+
http://infocenter.arm.com/help/topic/com.arm.doc.dui0491c/DUI0491C_arm_compiler_reference.pdf

‎src/ansi-c/ansi_c_language.h‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,6 @@ Author: Daniel Kroening, kroening@kroening.com
1010
#ifndef CPROVER_ANSI_C_ANSI_C_LANGUAGE_H
1111
#define CPROVER_ANSI_C_ANSI_C_LANGUAGE_H
1212

13-
/*! \defgroup gr_ansi_c ANSI-C front-end */
14-
1513
#include <memory>
1614

1715
#include <util/make_unique.h>

‎src/assembler/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
\ingroup module_hidden
12
\defgroup assembler assembler
23
# Folder assembler
34

‎src/big-int/README‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

0 commit comments

Comments
 (0)