Commit 7fd007d6 authored by Basile Desloges 's avatar Basile Desloges

[eacsl:doc] Update user manual with latest E-ACSL outputs and URL

parent 65caae73
...@@ -4,14 +4,14 @@ ...@@ -4,14 +4,14 @@
André Maroneze and Virgile Prevosto and André Maroneze and Virgile Prevosto and
Armand Puccetti and Julien Signoles and Armand Puccetti and Julien Signoles and
Boris Yakobowski}, Boris Yakobowski},
note = {\url{http://frama-c.cea.fr/download/user-manual.pdf}} note = {\url{https://frama-c.com/download/frama-c-user-manual.pdf}},
} }
@manual{plugin-dev-guide, @manual{plugin-dev-guide,
author = {Julien Signoles and Loïc Correnson and Matthieu Lemerre and author = {Julien Signoles and Loïc Correnson and Matthieu Lemerre and
Virgile Prevosto}, Virgile Prevosto},
title = {{Frama-C Plug-in Development Guide}}, title = {{Frama-C Plug-in Development Guide}},
note = {\newline \url{http://frama-c.cea.fr/download/plugin-developer.pdf}}, note = {\newline \url{https://frama-c.com/download/frama-c-plugin-development-guide.pdf}},
} }
@manual{eva, @manual{eva,
...@@ -19,7 +19,7 @@ ...@@ -19,7 +19,7 @@
Matthieu Lemerre and André Maroneze and Valentin Perelle and Matthieu Lemerre and André Maroneze and Valentin Perelle and
Virgile Prevosto}, Virgile Prevosto},
title = {{EVA} -- The Evolved Value Analysis plug-in}, title = {{EVA} -- The Evolved Value Analysis plug-in},
note = {\mbox{\url{http://frama-c.cea.fr/download/value-analysis.pdf}}}, note = {\mbox{\url{https://frama-c.com/download/frama-c-value-analysis.pdf}}},
} }
@manual{acsl, @manual{acsl,
...@@ -185,9 +185,15 @@ for C}}, ...@@ -185,9 +185,15 @@ for C}},
month = oct, month = oct,
} }
@article{pldi16, @inproceedings{vorobyov17ismm,
title = {{Shadow State Encoding for Efficient Monitoring of Block-level author = { Vorobyov, Kostyantyn and Signoles, Julien and Kosmatov, Nikolai },
Properties}}, booktitle = { International Symposium on Memory Management (ISMM) },
author = {Kostyantyn Vorobyov and Julien Signoles and Nikolai Kosmatov}, title = { Shadow State Encoding for Efficient Monitoring of Block-level Properties },
note = {Submitted for publication}, year = { 2017 },
month = jun,
pages = {47--58},
location = { Barcelona, Spain },
doi = { 10.1145/3092255 },
pdf = {publis/2017_ismm.pdf},
publisher = { {ACM} },
} }
...@@ -6,6 +6,7 @@ release. First we list changes of the last release. ...@@ -6,6 +6,7 @@ release. First we list changes of the last release.
\section*{E-ACSL \eacslpluginversion} \section*{E-ACSL \eacslpluginversion}
\begin{itemize} \begin{itemize}
\item Update every section with changes to \framac and \eacslgcc output
\item \textbf{Simple Example}: Remove option \texttt{-e-acsl-check} \item \textbf{Simple Example}: Remove option \texttt{-e-acsl-check}
\item \textbf{Combining E-ACSL with Other PLug-ins}: \texttt{-e-acsl-prepare} is \item \textbf{Combining E-ACSL with Other PLug-ins}: \texttt{-e-acsl-prepare} is
no more necessary. no more necessary.
...@@ -30,7 +31,7 @@ release. First we list changes of the last release. ...@@ -30,7 +31,7 @@ release. First we list changes of the last release.
\textbf{-e-acsl-prepare}. \textbf{-e-acsl-prepare}.
\item \textbf{Known Limitations}: Replace section ``Limitations of E-ACSL \item \textbf{Known Limitations}: Replace section ``Limitations of E-ACSL
Monitoring Libraries'' by the new section ``Supported Systems''. Monitoring Libraries'' by the new section ``Supported Systems''.
\item \textbf{Known Limitations}: Add limitation about monitoring of variables \item \textbf{Known Limitations}: Add limitation about monitoring of variables
with incomplete types. with incomplete types.
\end{itemize} \end{itemize}
......
void __e_acsl_assert(int pred, char *kind, void __e_acsl_assert(int pred, const char *kind, const char *func_name,
char *func_name, char *pred_text, int line); const char *pred_txt, const char * file, int line);
\begin{shell} \begin{shell}
\$ frama-c -e-acsl first.i -then-last -print \$ frama-c -e-acsl first.i -then-last -print
[kernel] Parsing FRAMAC_SHARE/e-acsl/e_acsl_gmp_api.h (with preprocessing)
[kernel] Parsing FRAMAC_SHARE/e-acsl/e_acsl.h (with preprocessing)
[kernel] Parsing first.i (no preprocessing) [kernel] Parsing first.i (no preprocessing)
[e-acsl] beginning translation. [e-acsl] beginning translation.
[kernel] Parsing FRAMAC_SHARE/e-acsl/e_acsl.h (with preprocessing)
[e-acsl] translation done in project "e-acsl". [e-acsl] translation done in project "e-acsl".
/* Generated by Frama-C */ /* Generated by Frama-C */
#include "stddef.h"
#include "stdio.h" #include "stdio.h"
#include "stdlib.h" struct __e_acsl_contract_t;
typedef struct __e_acsl_contract_t __attribute__((__FC_BUILTIN__)) __e_acsl_contract_t;
struct __e_acsl_mpz_struct { struct __e_acsl_mpz_struct {
int _mp_alloc ; int _mp_alloc ;
int _mp_size ; int _mp_size ;
...@@ -15,39 +16,56 @@ struct __e_acsl_mpz_struct { ...@@ -15,39 +16,56 @@ struct __e_acsl_mpz_struct {
}; };
typedef struct __e_acsl_mpz_struct __e_acsl_mpz_struct; typedef struct __e_acsl_mpz_struct __e_acsl_mpz_struct;
typedef __e_acsl_mpz_struct ( __attribute__((__FC_BUILTIN__)) __e_acsl_mpz_t)[1]; typedef __e_acsl_mpz_struct ( __attribute__((__FC_BUILTIN__)) __e_acsl_mpz_t)[1];
/*@ ghost extern int __e_acsl_init; */ struct __e_acsl_mpq_struct {
__e_acsl_mpz_struct _mp_num ;
__e_acsl_mpz_struct _mp_den ;
};
typedef struct __e_acsl_mpq_struct __e_acsl_mpq_struct;
typedef __e_acsl_mpq_struct ( __attribute__((__FC_BUILTIN__)) __e_acsl_mpq_t)[1];
typedef unsigned long __e_acsl_mp_bitcnt_t;
/*@ requires pred != 0; /*@ requires pred != 0;
assigns \nothing; */ assigns \nothing; */
__attribute__((__FC_BUILTIN__)) void __e_acsl_assert(int pred, char *kind, __attribute__((__FC_BUILTIN__)) void __e_acsl_assert(int pred,
char *fct, char const *kind,
char *pred_txt, char const *fct,
char const *pred_txt,
char const *file,
int line); int line);
/*@ assigns \nothing; */
__attribute__((__FC_BUILTIN__)) void __e_acsl_memory_init(int *argc_ref,
char ***argv,
size_t ptr_size);
extern size_t __e_acsl_heap_allocation_size; extern size_t __e_acsl_heap_allocation_size;
/*@ extern size_t __e_acsl_heap_allocated_blocks;
predicate diffSize{L1, L2}(integer i) =
\at(__e_acsl_heap_allocation_size,L1) - /*@ ghost extern int __fc_heap_status __attribute__((__FRAMA_C_MODEL__)); */
\at(__e_acsl_heap_allocation_size,L2) == i;
/*@ ghost extern int __e_acsl_init; */
long valid_nstring(char *s, long n, int wrtbl);
long valid_nwstring(wchar_t *s, long n, int wrtbl);
__inline static long valid_string__fc_inline(char *s, int wrtbl)
{
long tmp;
tmp = valid_nstring(s,(long)(-1),wrtbl);
return tmp;
}
__inline static long valid_wstring__fc_inline(wchar_t *s, int wrtbl)
{
long tmp;
tmp = valid_nwstring(s,(long)(-1),wrtbl);
return tmp;
}
*/
int main(void) int main(void)
{ {
int __retres; int __retres;
__e_acsl_memory_init((int *)0,(char ***)0,(size_t)4);
int x = 0; int x = 0;
/*@ assert x == 0; */ __e_acsl_assert(x == 0,"Assertion","main","x == 0","first.i",3);
__e_acsl_assert(x == 0,(char *)"Assertion",(char *)"main",(char *)"x == 0", /*@ assert x == 0; */ ;
3); __e_acsl_assert(x == 1,"Assertion","main","x == 1","first.i",4);
/*@ assert x == 1; */ /*@ assert x == 1; */ ;
__e_acsl_assert(x == 1,(char *)"Assertion",(char *)"main",(char *)"x == 1",
4);
__retres = 0; __retres = 0;
return __retres; return __retres;
} }
......
...@@ -2,14 +2,15 @@ ...@@ -2,14 +2,15 @@
extern int __e_acsl_sound_verdict; extern int __e_acsl_sound_verdict;
void __e_acsl_assert(int pred, char *kind, void __e_acsl_assert(int pred, const char *kind, const char *func_name,
char *func_name, char *pred_text, int line) { const char *pred_text, const char *file, int line) {
printf("%s at line %d in function %s is %s (%s).\n\ printf("%s in file %s at line %d in function %s is %s (%s).\n\
The verified predicate was: `%s'.\n", The verified predicate was: `%s'.\n",
kind, kind,
file,
line, line,
func_name, func_name,
pred ? "valid" : "invalid", pred ? "valid" : "invalid",
__e_acsl_sound_verdict ? "trustable" : "UNTRUSTABLE", __e_acsl_sound_verdict ? "trustworthy" : "UNTRUSTWORTHY",
pred_text); pred_text);
} }
...@@ -15,7 +15,7 @@ program. ...@@ -15,7 +15,7 @@ program.
checking''~\cite{runtime-assertion-checking}\footnote{In our context, ``runtime checking''~\cite{runtime-assertion-checking}\footnote{In our context, ``runtime
annotation checking'' would be more precise.}. This is the primary goal of annotation checking'' would be more precise.}. This is the primary goal of
\eacsl. Indirectly, in combination with the \rte plug-in~\cite{rte} of \framac, \eacsl. Indirectly, in combination with the \rte plug-in~\cite{rte} of \framac,
this this
usage allows the user to detect undefined behaviors in its \C code. Second, it usage allows the user to detect undefined behaviors in its \C code. Second, it
allows to combine \framac and its existing analyzers with other \C analyzers allows to combine \framac and its existing analyzers with other \C analyzers
that do not natively understand the \acsl specification language. Third, the that do not natively understand the \acsl specification language. Third, the
...@@ -38,10 +38,12 @@ previous paragraph. Using \eacsl this way is therefore a fully automatic ...@@ -38,10 +38,12 @@ previous paragraph. Using \eacsl this way is therefore a fully automatic
process. Many usages, including automatic usages, are described in companion process. Many usages, including automatic usages, are described in companion
research papers~\cite{rv13tutorial,rvcubes17tool,signoles18hdr}. research papers~\cite{rv13tutorial,rvcubes17tool,signoles18hdr}.
This manual does \emph{not} explain how to install the \eacsl plug-in. For The \eacsl plug-in is installed with \framac, but this manual does \emph{not}
installation instructions please refer to the \texttt{INSTALL} file in the explain how to install \framac. For installation instructions please refer to
\eacsl distribution. \index{Installation} Furthermore, even though this manual the \texttt{INSTALL}\footnote{
provides examples, it is \emph{not} a full comprehensive tutorial on \url{https://git.frama-c.com/pub/frama-c/blob/master/INSTALL.md}}
file in the \framac distribution. \index{Installation} Furthermore, even though
this manual provides examples, it is \emph{not} a full comprehensive tutorial on
\framac or \eacsl. \framac or \eacsl.
% You can still refer to any external % You can still refer to any external
% tutorial~\cite{rv13tutorial} for additional examples. % tutorial~\cite{rv13tutorial} for additional examples.
...@@ -5,12 +5,13 @@ reference manual~\cite{eacsl} is not yet fully supported. Which annotations can ...@@ -5,12 +5,13 @@ reference manual~\cite{eacsl} is not yet fully supported. Which annotations can
already be translated into \C code and which cannot is defined in a separate already be translated into \C code and which cannot is defined in a separate
document~\cite{eacsl-implem}. Second, even though we do our best to avoid them, document~\cite{eacsl-implem}. Second, even though we do our best to avoid them,
bugs may exist. If you find a new one, please report it on the bug tracking bugs may exist. If you find a new one, please report it on the bug tracking
system\footnote{\url{http://bts.frama-c.com}} (see Chapter 10 of the \framac system\footnote{\url{https://git.frama-c.com/pub/frama-c/-/issues}} (see Chapter
User Manual~\cite{userman}). Third, there 10 of the \framac User Manual~\cite{userman}). Third, there are some additional
are some additional known limitations, which could be annoying for the user in known limitations, which could be annoying for the user in some cases, but are
some cases, but are tedious to lift. Please contact us if you are interested in tedious to lift. Please contact us if you are interested in lifting these
lifting these limitations\footnote{Read \url{http://frama-c.com/support.html} limitations\footnote{Read
for additional details.}. \url{https://git.frama-c.com/pub/frama-c/blob/master/CONTRIBUTING.md} for
additional details.}.
\section{Supported Systems} \section{Supported Systems}
...@@ -53,8 +54,8 @@ may get no runtime error depending on your \C compiler, but the behavior is ...@@ -53,8 +54,8 @@ may get no runtime error depending on your \C compiler, but the behavior is
actually undefined because the assertion reads the uninitialized variable actually undefined because the assertion reads the uninitialized variable
\lstinline|x|. You should be caught by the \eacsl plug-in, but that is not \lstinline|x|. You should be caught by the \eacsl plug-in, but that is not
the case yet. the case yet.
\begin{shell}
\begin{shell}
\$ e-acsl-gcc.sh uninitialized.i -c -Omonitored_uninitialized \$ e-acsl-gcc.sh uninitialized.i -c -Omonitored_uninitialized
monitored_uninitialized.i: In function 'main': monitored_uninitialized.i: In function 'main':
monitored_uninitialized.i:44:16: warning: 'x' is used uninitialized in this function monitored_uninitialized.i:44:16: warning: 'x' is used uninitialized in this function
...@@ -98,22 +99,26 @@ Consider the following example. ...@@ -98,22 +99,26 @@ Consider the following example.
You can generate the instrumented program as follows. You can generate the instrumented program as follows.
\begin{shell} \begin{shell}
\$ e-acsl-gcc.sh -ML -omonitored_valid_no_main.i valid_no_main.c \$ e-acsl-gcc.sh -M -omonitored_valid_no_main.i valid_no_main.c
<skip preprocessing commands> [kernel] Parsing valid_no_main.c (with preprocessing)
[e-acsl] beginning translation. [e-acsl] beginning translation.
<skip warnings about annotations from the Frama-C libc [kernel] Parsing FRAMAC_SHARE/e-acsl/e_acsl.h (with preprocessing)
which cannot be translated> [kernel] Warning: no entry point specified:
[kernel] warning: no entry point specified: you must call functions `__e_acsl_globals_init', `__e_acsl_globals_clean',
you must call function `__e_acsl_memory_init' by yourself. `__e_acsl_memory_init' and `__e_acsl_memory_clean' by yourself.
[e-acsl] translation done in project "e-acsl". [e-acsl] translation done in project "e-acsl".
\end{shell} \end{shell}
The last warning states an important point: if this program is linked against The last warning states an important point: if this program is linked against
another file containing \texttt{main} function, then this main function must another file containing \texttt{main} function, then this main function must
be modified to insert a call to the function \texttt{\_\_e\_acsl\_memory\_init} be modified to insert a calls to the functions
\texttt{\_\_e\_acsl\_globals\_init}
\index{e\_acsl\_globals\_init@\texttt{\_\_e\_acsl\_globals\_init}} and
\texttt{\_\_e\_acsl\_memory\_init}
\index{e\_acsl\_memory\_init@\texttt{\_\_e\_acsl\_memory\_init}} at the very \index{e\_acsl\_memory\_init@\texttt{\_\_e\_acsl\_memory\_init}} at the very
beginning. This function plays a very important role: it initializes metadata beginning. These functions play a very important role: the latter initializes
storage used for tracking of memory blocks. Unless this call is inserted the metadata storage used for tracking of memory blocks while the former initializes
tracking of global variables and constants. Unless these calls are inserted the
run of a modified program is likely to fail. run of a modified program is likely to fail.
While it is possible to add such intrumentation manually we recommend using While it is possible to add such intrumentation manually we recommend using
...@@ -125,7 +130,7 @@ While it is possible to add such intrumentation manually we recommend using ...@@ -125,7 +130,7 @@ While it is possible to add such intrumentation manually we recommend using
Then just compile and run it as explained in Section~\ref{sec:memory}. Then just compile and run it as explained in Section~\ref{sec:memory}.
\begin{shell} \begin{shell}
\$ e-acsl-gcc.sh -M -omonitored_modified_main.i modified_main.c \$ e-acsl-gcc.sh -M -omonitored_modified_main.i modified_main.c
\$ e-acsl-gcc.sh -C -Ovalid_no_main monitored_modified_main.i monitored_valid_no_main.i \$ e-acsl-gcc.sh -C -Ovalid_no_main monitored_modified_main.i monitored_valid_no_main.i
\$ ./valid_no_main.e-acsl \$ ./valid_no_main.e-acsl
Assertion failed at line 11 in function f. Assertion failed at line 11 in function f.
...@@ -192,7 +197,7 @@ functions. ...@@ -192,7 +197,7 @@ functions.
\subsection{\eacsl Namespace} \subsection{\eacsl Namespace}
While \eacsl uses source-to-source transformations and not binary While \eacsl uses source-to-source transformations and not binary
instrumentations it is important that the source code provided at input does instrumentations it is important that the source code provided as input does
not contain any variables or functions prefixed \T{\_\_e\_acsl\_}. \eacsl not contain any variables or functions prefixed \T{\_\_e\_acsl\_}. \eacsl
reserves this namespace for its transformations, and therefore an input program reserves this namespace for its transformations, and therefore an input program
containing such symbols beforehand may fail to be instrumented or compiled. containing such symbols beforehand may fail to be instrumented or compiled.
......
...@@ -20,7 +20,7 @@ ...@@ -20,7 +20,7 @@
\title{\eacsl Plug-in}{Release \eacslpluginversion \title{\eacsl Plug-in}{Release \eacslpluginversion
\ifthenelse{\equal{\eacslpluginversion}{\fcversion}}{}{% \ifthenelse{\equal{\eacslpluginversion}{\fcversion}}{}{%
\\[1em] compatible with \framac \fcversion}} \\[1em] compatible with \framac \fcversion}}
\author{Julien Signoles and Kostyantyn Vorobyov} \author{Julien Signoles, Basile Desloges and Kostyantyn Vorobyov}
\begin{center} \begin{center}
CEA LIST\\ Software Reliability \& Security Laboratory CEA LIST\\ Software Reliability \& Security Laboratory
\end{center} \end{center}
...@@ -41,8 +41,8 @@ CEA LIST\\ Software Reliability \& Security Laboratory ...@@ -41,8 +41,8 @@ CEA LIST\\ Software Reliability \& Security Laboratory
\addcontentsline{toc}{chapter}{Foreword} \addcontentsline{toc}{chapter}{Foreword}
This is the user manual of the \framac plug-in This is the user manual of the \framac plug-in
\eacsl\footnote{\url{https://frama-c.com/eacsl.html}}. The contents of this \eacsl\footnote{\url{https://frama-c.com/fc-plugins/e-acsl.html}}. The contents
document correspond to its version \eacslpluginversion compatible with of this document correspond to its version \eacslpluginversion compatible with
\fcversion version of \framac~\cite{userman,fac15}. The development of \fcversion version of \framac~\cite{userman,fac15}. The development of
the \eacsl plug-in is still ongoing. Features described by this document may the \eacsl plug-in is still ongoing. Features described by this document may
evolve in the future. evolve in the future.
...@@ -50,9 +50,8 @@ evolve in the future. ...@@ -50,9 +50,8 @@ evolve in the future.
\section*{Acknowledgements} \section*{Acknowledgements}
We gratefully thank the people who contributed to this document: We gratefully thank the people who contributed to this document:
Basile Desloges, Pierre-Lo\"ic Garoche, Jens Gerlach, Florent Kirchner, Pierre-Lo\"ic Garoche, Jens Gerlach, Florent Kirchner, Nikola\"i Kosmatov,
Nikola\"i Kosmatov, Andr\'e Oliveira Maroneze, Fonenantsoa Maurica, and Andr\'e Oliveira Maroneze, Fonenantsoa Maurica, and Guillaume Petiot.
Guillaume Petiot.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
......
This diff is collapsed.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment