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

src/plugins/e-acsl/doc/userman/biblio.bib

@@ -4,14 +4,14 @@
             André Maroneze and Virgile Prevosto and
             Armand Puccetti and Julien Signoles and
             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,
   author = {Julien Signoles and Loïc Correnson and Matthieu Lemerre and
             Virgile Prevosto},
   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,
@@ -19,7 +19,7 @@
             Matthieu Lemerre and André Maroneze and Valentin Perelle and
             Virgile Prevosto},
   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,
@@ -185,9 +185,15 @@ for C}},
   month     = oct,
 }
 
-@article{pldi16,
-  title  = {{Shadow State Encoding for Efficient Monitoring of Block-level
-Properties}},
-  author = {Kostyantyn Vorobyov and Julien Signoles and Nikolai Kosmatov},
-  note   = {Submitted for publication},
+@inproceedings{vorobyov17ismm,
+  author    = { Vorobyov, Kostyantyn and Signoles, Julien and Kosmatov, Nikolai },
+  booktitle = { International Symposium on Memory Management (ISMM)  },
+  title     = { Shadow State Encoding for Efficient Monitoring of Block-level Properties },
+  year      = { 2017 },
+  month     = jun,
+  pages     = {47--58},
+  location  = { Barcelona, Spain },
+  doi       = { 10.1145/3092255 },
+  pdf       = {publis/2017_ismm.pdf},
+  publisher = { {ACM} },
 }

src/plugins/e-acsl/doc/userman/changes.tex

@@ -6,6 +6,7 @@ release. First we list changes of the last release.
 \section*{E-ACSL \eacslpluginversion}
 
 \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{Combining E-ACSL with Other PLug-ins}: \texttt{-e-acsl-prepare} is
   no more necessary.
@@ -30,7 +31,7 @@ release. First we list changes of the last release.
   \textbf{-e-acsl-prepare}.
 \item \textbf{Known Limitations}: Replace section ``Limitations of E-ACSL
   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.
 \end{itemize}
 

src/plugins/e-acsl/doc/userman/examples/assert_sign.c

-void __e_acsl_assert(int pred, char *kind,
-                     char *func_name, char *pred_text, int line);
+void __e_acsl_assert(int pred, const char *kind, const char *func_name,
+    const char *pred_txt, const char * file, int line);

src/plugins/e-acsl/doc/userman/examples/instrumented_first.c

 \begin{shell}
 \$ 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)
 [e-acsl] beginning translation.
+[kernel] Parsing FRAMAC_SHARE/e-acsl/e_acsl.h (with preprocessing)
 [e-acsl] translation done in project "e-acsl".
 /* Generated by Frama-C */
+#include "stddef.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 {
    int _mp_alloc ;
    int _mp_size ;
@@ -15,39 +16,56 @@ 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];
-/*@ 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;
     assigns \nothing; */
- __attribute__((__FC_BUILTIN__)) void __e_acsl_assert(int pred, char *kind,
-                                                      char *fct,
-                                                      char *pred_txt,
+ __attribute__((__FC_BUILTIN__)) void __e_acsl_assert(int pred,
+                                                      char const *kind,
+                                                      char const *fct,
+                                                      char const *pred_txt,
+                                                      char const *file,
                                                       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;
 
-/*@
-predicate diffSize{L1, L2}(integer i) =
-  \at(__e_acsl_heap_allocation_size,L1) -
-  \at(__e_acsl_heap_allocation_size,L2) == i;
+extern size_t __e_acsl_heap_allocated_blocks;
+
+/*@ ghost extern int __fc_heap_status __attribute__((__FRAMA_C_MODEL__)); */
+
+/*@ 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 __retres;
-  __e_acsl_memory_init((int *)0,(char ***)0,(size_t)4);
   int x = 0;
-  /*@ assert x == 0; */
-  __e_acsl_assert(x == 0,(char *)"Assertion",(char *)"main",(char *)"x == 0",
-                  3);
-  /*@ assert x == 1; */
-  __e_acsl_assert(x == 1,(char *)"Assertion",(char *)"main",(char *)"x == 1",
-                  4);
+  __e_acsl_assert(x == 0,"Assertion","main","x == 0","first.i",3);
+  /*@ assert x == 0; */ ;
+  __e_acsl_assert(x == 1,"Assertion","main","x == 1","first.i",4);
+  /*@ assert x == 1; */ ;
   __retres = 0;
   return __retres;
 }

src/plugins/e-acsl/doc/userman/examples/my_assert.c

@@ -2,14 +2,15 @@
 
 extern int __e_acsl_sound_verdict;
 
-void __e_acsl_assert(int pred, char *kind,
-                     char *func_name, char *pred_text, int line) {
-  printf("%s at line %d in function %s is %s (%s).\n\
+void __e_acsl_assert(int pred, const char *kind, const char *func_name,
+                     const char *pred_text, const char *file, int line) {
+  printf("%s in file %s at line %d in function %s is %s (%s).\n\
 The verified predicate was: `%s'.\n",
     kind,
+    file,
     line,
     func_name,
     pred ? "valid" : "invalid",
-    __e_acsl_sound_verdict ? "trustable" : "UNTRUSTABLE",
+    __e_acsl_sound_verdict ? "trustworthy" : "UNTRUSTWORTHY",
     pred_text);
 }

src/plugins/e-acsl/doc/userman/introduction.tex

@@ -15,7 +15,7 @@ program.
 checking''~\cite{runtime-assertion-checking}\footnote{In our context, ``runtime
   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,
-this 
+this
 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
 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
 process. Many usages, including automatic usages, are described in companion
 research papers~\cite{rv13tutorial,rvcubes17tool,signoles18hdr}.
 
-This manual does \emph{not} explain how to install the \eacsl plug-in.  For
-installation instructions please refer to the \texttt{INSTALL} file in the
-\eacsl distribution. \index{Installation} Furthermore, even though this manual
-provides examples, it is \emph{not} a full comprehensive tutorial on
+The \eacsl plug-in is installed with \framac, but this manual does \emph{not}
+explain how to install \framac.  For installation instructions please refer to
+the \texttt{INSTALL}\footnote{
+  \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.
 % You can still refer to any external
 % tutorial~\cite{rv13tutorial} for additional examples.

src/plugins/e-acsl/doc/userman/limitations.tex

@@ -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
 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
-system\footnote{\url{http://bts.frama-c.com}} (see Chapter 10 of the \framac
-User Manual~\cite{userman}). Third, there
-are some additional known limitations, which could be annoying for the user in
-some cases, but are tedious to lift. Please contact us if you are interested in
-lifting these limitations\footnote{Read \url{http://frama-c.com/support.html}
-  for additional details.}.
+system\footnote{\url{https://git.frama-c.com/pub/frama-c/-/issues}} (see Chapter
+10 of the \framac User Manual~\cite{userman}). Third, there are some additional
+known limitations, which could be annoying for the user in some cases, but are
+tedious to lift. Please contact us if you are interested in lifting these
+limitations\footnote{Read
+  \url{https://git.frama-c.com/pub/frama-c/blob/master/CONTRIBUTING.md} for
+  additional details.}.
 
 \section{Supported Systems}
 
@@ -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
 \lstinline|x|. You should be caught by the \eacsl plug-in, but that is not
 the case yet.
-\begin{shell}
 
+\begin{shell}
 \$ e-acsl-gcc.sh uninitialized.i -c -Omonitored_uninitialized
 monitored_uninitialized.i: In function 'main':
 monitored_uninitialized.i:44:16: warning: 'x' is used uninitialized in this function
@@ -98,22 +99,26 @@ Consider the following example.
 
 You can generate the instrumented program as follows.
 \begin{shell}
-\$ e-acsl-gcc.sh -ML -omonitored_valid_no_main.i valid_no_main.c
-<skip preprocessing commands>
+\$ e-acsl-gcc.sh -M -omonitored_valid_no_main.i valid_no_main.c
+[kernel] Parsing valid_no_main.c (with preprocessing)
 [e-acsl] beginning translation.
-<skip warnings about annotations from the Frama-C libc
-  which cannot be translated>
-[kernel] warning: no entry point specified:
-  you must call function `__e_acsl_memory_init' by yourself.
+[kernel] Parsing FRAMAC_SHARE/e-acsl/e_acsl.h (with preprocessing)
+[kernel] Warning: no entry point specified:
+  you must call functions `__e_acsl_globals_init', `__e_acsl_globals_clean',
+  `__e_acsl_memory_init' and `__e_acsl_memory_clean' by yourself.
 [e-acsl] translation done in project "e-acsl".
 \end{shell}
 
 The last warning states an important point: if this program is linked against
 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
-beginning. This function plays a very important role: it initializes metadata
-storage used for tracking of memory blocks. Unless this call is inserted the
+beginning. These functions play a very important role: the latter initializes
+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.
 
 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}.
 
 \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
 \$ ./valid_no_main.e-acsl
 Assertion failed at line 11 in function f.
@@ -192,7 +197,7 @@ functions.
 
 \subsection{\eacsl Namespace}
 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
 reserves this namespace for its transformations, and therefore an input program
 containing such symbols beforehand may fail to be instrumented or compiled.

src/plugins/e-acsl/doc/userman/main.tex

@@ -20,7 +20,7 @@
 \title{\eacsl Plug-in}{Release \eacslpluginversion
  \ifthenelse{\equal{\eacslpluginversion}{\fcversion}}{}{%
    \\[1em] compatible with \framac \fcversion}}
-\author{Julien Signoles and Kostyantyn Vorobyov}
+\author{Julien Signoles, Basile Desloges and Kostyantyn Vorobyov}
 \begin{center}
 CEA LIST\\ Software Reliability \& Security Laboratory
 \end{center}
@@ -41,8 +41,8 @@ CEA LIST\\ Software Reliability \& Security Laboratory
 \addcontentsline{toc}{chapter}{Foreword}
 
 This is the user manual of the \framac plug-in
-\eacsl\footnote{\url{https://frama-c.com/eacsl.html}}. The contents of this
-document correspond to its version \eacslpluginversion compatible with
+\eacsl\footnote{\url{https://frama-c.com/fc-plugins/e-acsl.html}}. The contents
+of this document correspond to its version \eacslpluginversion compatible with
 \fcversion version of \framac~\cite{userman,fac15}.  The development of
 the \eacsl plug-in is still ongoing.  Features described by this document may
 evolve in the future.
@@ -50,9 +50,8 @@ evolve in the future.
 \section*{Acknowledgements}
 
 We gratefully thank the people who contributed to this document:
-Basile Desloges, Pierre-Lo\"ic Garoche, Jens Gerlach, Florent Kirchner,
-Nikola\"i Kosmatov, Andr\'e Oliveira Maroneze, Fonenantsoa Maurica, and
-Guillaume Petiot.
+Pierre-Lo\"ic Garoche, Jens Gerlach, Florent Kirchner, Nikola\"i Kosmatov,
+Andr\'e Oliveira Maroneze, Fonenantsoa Maurica, and Guillaume Petiot.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%