Skip to content

Commit

Permalink
documentation update
Browse files Browse the repository at this point in the history
  • Loading branch information
@lathuili
lathuili committed May 7, 2024
1 parent be17e6e commit dfbbeb1
Show file tree
Hide file tree
Showing 7 changed files with 340 additions and 93 deletions.
18 changes: 16 additions & 2 deletions docs/verrou_dd-manpage.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,17 @@
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="vr-manual.xml" xpointer="vr-manual.verrou_dd_line.synopsis"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="vr-manual.xml" xpointer="vr-manual.verrou_dd_task.synopsis"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="vr-manual.xml" xpointer="vr-manual.verrou_dd_stdout.synopsis"
xmlns:xi="http://www.w3.org/2001/XInclude" />
</refsynopsisdiv>

<refsect1>
<title>Principle</title>
<xi:include href="vr-manual.xml" xpointer="vr-manual.dd.principle"
xmlns:xi="http://www.w3.org/2001/XInclude" />
</refsect1>

<refsect1>
<title>Description</title>
Expand All @@ -41,6 +48,12 @@
xmlns:xi="http://www.w3.org/2001/XInclude" />
</refsect1>

<refsect1>
<title>Option and Environment Variable specific to verrou_dd_task and verrou_dd_stdout </title>
<xi:include href="vr-manual.xml" xpointer="verrou_dd_task_stdout.specific.option"
xmlns:xi="http://www.w3.org/2001/XInclude" />
</refsect1>

<refsect1>
<title>Options and Environment Variables specific to verrou_dd_stdout</title>
<xi:include href="vr-manual.xml" xpointer="verrou_dd_stdout.specific.option"
Expand All @@ -51,8 +64,9 @@
<title>See Also</title>
<para>
valgrind(1),
<filename>&vg-docs-path;</filename> or
<filename>&vg-docs-url;</filename>.
verrou_plot_stat(1),
post_verrou_dd(1),
<filename>&vg-docs-path;</filename>.
</para>
</refsect1>

Expand Down
288 changes: 220 additions & 68 deletions docs/vr-localization.xml
View file

Large diffs are not rendered by default.

94 changes: 75 additions & 19 deletions docs/vr-manual.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -319,12 +319,12 @@ det2
<command>manual_exclude</command> : The automatic detection is ignored and the user has to define manually the exclusion thanks <command>--exclude</command> option. This option is useful if the pattern detection detect object you need to perturb.
</para></listitem>
<listitem><para>
<command>instrumented</command> : the interposition library Interlibmath is loaded. This option is valid only with verrou backend. This option imply implicitly the libm exclusion.
<command>instrumented</command> : the interposition library Interlibmath is loaded (The complex libm function are not yet instrumented). This option is valid only with verrou backend. This option imply implicitly the libm exclusion.
</para></listitem>
</itemizedlist>

<para>
The option <command>instrumented</command> is not yet compatible with verrou_dd_sym and verrou_dd_line. When it will be the case, the default will switch from <command>auto_exclude</command> to <command>instrumented</command>
The option <command>instrumented</command> is quite new. In a near future, the default will switch from <command>auto_exclude</command> to <command>instrumented</command>
</para>
</listitem>
</varlistentry>
Expand Down Expand Up @@ -446,6 +446,7 @@ det2
<term><option><![CDATA[--vr-instr-scalar=<yes|no> [default=no]]]></option></term>
<listitem><para>
Toggle instrumentation of x387 scalar instructions.
On arm64 architecture, this option is set by default to yes, as scalar instructions respect the IEEE standard.
</para></listitem>
</varlistentry>

Expand All @@ -469,8 +470,7 @@ det2
</para></listitem>
</varlistentry>


<varlistentry id="vr-opt.instr-[flt|dbl]" xreflabel="--vr-instr-[flt|dbl]-">
<varlistentry id="vr-opt.instr-[flt|dbl]" xreflabel="--vr-instr-[flt|dbl]-">
<term><option><![CDATA[--vr-instr-[flt|dbl]=<yes|no> [default=yes]]]></option></term>
<listitem><para>
Toggle instrumentation of float (or double) instructions.
Expand All @@ -487,14 +487,25 @@ det2

<varlistentry id="vr-opt.instr-atstart" xreflabel="--instr-atstart">
<term><option><![CDATA[--instr-atstart=<yes|no> [default=yes]]]></option></term>
<listitem><para>Toggle <link linkend="vr-manual.feat.instr">instrumentation
state</link> on or off at program start. Useful in combination
<listitem><para>Toggle <link linkend="vr-manual.feat.instr">hard instrumentation
state</link> on or off at program start. Useful in combination
with <link linkend="vr-cr.start-instrumentation">client
requests</link>.
</para>
<para>This option can be activated with the env variable <command>VERROU_INSTR_ATSTART</command>.</para>
</listitem>
</varlistentry>
requests</link>.
</para>
<para>This option can be activated with the env variable <command>VERROU_INSTR_ATSTART</command>.</para>
</listitem>
</varlistentry>

<varlistentry id="vr-opt.instr-atstart-soft" xreflabel="--instr-atstart-soft">
<term><option><![CDATA[--instr-atstart-soft=<yes|no> [default=yes]]]></option></term>
<listitem><para>Toggle <link linkend="vr-manual.feat.instr">soft instrumentation
state</link> on or off at program start. Useful in combination
with <link linkend="vr-cr.start-instrumentation">client
requests</link>.
</para>
<para>This option can be activated with the env variable <command>VERROU_INSTR_ATSTART_SOFT</command>.</para>
</listitem>
</varlistentry>

<varlistentry id="vr-opt.exclude" xreflabel="--exclude">
<term><option><![CDATA[--exclude=FILE]]></option></term>
Expand Down Expand Up @@ -571,6 +582,8 @@ det2
<para> When this option is present the expect script is read. This file
defines the interaction between verrou and the stdout (<link linkend= "id.expect.format">See expect format</link>). The main idea behind this format is to apply client request action when a line match a MATCH or EXPECT line. A MATCH line can be match anytime, whereas the EXPECT lines are matched sequentially.</para>

<para> The use of this option, may be sensitive to the bufferization of the program. In C++ std::endl flush the output, so we usually avoid the problem. In python, you can use PYTHONUNBUFFERED env variable. In C we proposed the library <computeroutput>verrouUnbuffered.so</computeroutput> (Loadable with LD_PRELOAD), to deactivate bufferization of stdout (For other file descriptors you have to flush manually, as it require more complex development). <computeroutput> verrou_dd_task</computeroutput> automatically use this two tricks.
</para>
<para>This option can be activated with the env variable <command>VERROU_EXPECT_CLR</command>.</para>
</listitem>
</varlistentry>
Expand All @@ -596,14 +609,18 @@ det2
<term><option><![CDATA[--trace=FILE]]></option></term>
<listitem><para>
Activate the <link linkend="vr-manual.localization.CovBB" >Basic Blocks Coverage</link> for the symbols specified in <computeroutput> FILE</computeroutput>.
</para></listitem>
</para>
<para>This option can be activated with the env variable <command>VERROU_TRACE</command>.</para>
</listitem>
</varlistentry>

<varlistentry id="vr.opt.output-trace-rep" xreflabel="--output-trace-rep">
<term><option><![CDATA[--output-trace-rep=REP]]></option></term>
<listitem><para>
Specify the <computeroutput>REP</computeroutput> directory for the trace output files.
</para></listitem>
</para>
<para>This option can be activated with the env variable <command>VERROU_OUTPUT_TRACE_REP</command>.</para>
</listitem>
</varlistentry>
</variablelist>

Expand Down Expand Up @@ -730,17 +747,34 @@ det2
<varlistentry id="vr-cr.start-instrumentation"
xreflabel="VERROU_START_INSTRUMENTATION">
<term><computeroutput>VERROU_START_INSTRUMENTATION</computeroutput></term>
<listitem><para>Start full
Verrou <link linkend="vr-manual.feat.instr">instrumentation</link>
<listitem><para>Start
Verrou <link linkend="vr-manual.feat.instr">hard instrumentation</link>
(including rounding mode switching) if not already
enabled.</para></listitem>
</varlistentry>

<varlistentry id="vr-cr.stop-instrumentation"
xreflabel="VERROU_STOP_INSTRUMENTATION">
<term><computeroutput>VERROU_STOP_INSTRUMENTATION</computeroutput></term>
<listitem><para>Stop
Verrou <link linkend="vr-manual.feat.instr">hard instrumentation</link>
(don't switch rounding modes) if not already disabled.</para></listitem>
</varlistentry>

<varlistentry id="vr-cr.start-soft-instrumentation"
xreflabel="VERROU_START_SOFT_INSTRUMENTATION">
<term><computeroutput>VERROU_START_SOFT_INSTRUMENTATION</computeroutput></term>
<listitem><para>Start full
Verrou <link linkend="vr-manual.feat.instr">soft instrumentation</link>
(including rounding mode switching) if not already
enabled.</para></listitem>
</varlistentry>

<varlistentry id="vr-cr.stop-soft-instrumentation"
xreflabel="VERROU_STOP_SOFT_INSTRUMENTATION">
<term><computeroutput>VERROU_STOP_SOFT_INSTRUMENTATION</computeroutput></term>
<listitem><para>Stop full
Verrou <link linkend="vr-manual.feat.instr">instrumentation</link>
Verrou <link linkend="vr-manual.feat.instr">soft instrumentation</link>
(don't switch rounding modes) if not already disabled.</para></listitem>
</varlistentry>

Expand Down Expand Up @@ -819,7 +853,7 @@ det2
</listitem>

<para>
The first argument of <computeroutput>CMD</computeroutput> has to be a path absolute (or relative if there is no CWD change). This option is not (yet) able to read the <computeroutput>$PATH</computeroutput> env variable. All the space are used to separate command arguments. To prevent this behaviour, the only way is to escape the space by a backslash. </para>
The first argument of <computeroutput>CMD</computeroutput> has to be a path absolute (or relative if there is no CWD change). This option is not (yet) able to read the <computeroutput>$PATH</computeroutput> env variable. All the space are used to separate command arguments. To prevent this behaviour, the only way is to escape the space by a backslash.</para>

<para>
If there are two many calls to this command (ie. too many line in stdout), there are a known bug. You can detected with the valgrind Warning like this one:<programlisting>--20481-- warning: Unable to record PID of internal process (pipe)</programlisting>
Expand All @@ -838,14 +872,14 @@ det2
<term><computeroutput>dump-filtered-stdout: [FILENAME]</computeroutput></term>
<listitem>
Dump the stdout file after application of <computeroutput>filter_line_exec CMD</computeroutput> to each line.
If FILENAME is not set the default name is <computeroutput>EXPECT_FILE.filtered.stdout-PID</computeroutput> or <computeroutput>EXPECT_OUTPUT_REP/expect.filtered.stdout-PID</computeroutput> (if option <option>--output-expect-rep=EXPECT_OUTPUT_REP</option> is used). Remark: <computeroutput>FILENAME</computeroutput> absolute path and <option>--output-expect-rep=</option> are incompatible.
If FILENAME is not set the default name is <computeroutput>EXPECT_FILE.filtered.stdout-PID</computeroutput> (or <computeroutput>EXPECT_OUTPUT_REP/expect.filtered.stdout-PID</computeroutput> if option <option>--output-expect-rep=EXPECT_OUTPUT_REP</option> is used). Remark: <computeroutput>FILENAME</computeroutput> absolute path and <option>--output-expect-rep=</option> are incompatible.
</listitem>
</varlistentry>
</variablelist>

</para>
<para>
In the <replaceable>header part</replaceable> we can also set up action to each section.
In the <replaceable>header part</replaceable> we can also set up action for each section.
<variablelist>
<varlistentry>
<term><computeroutput>default: ACTION</computeroutput></term>
Expand Down Expand Up @@ -911,6 +945,18 @@ The different possible actions are :
Stop instrumentation.
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>start_soft</computeroutput></term>
<listitem> Start soft instrumentation.
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>stop_soft</computeroutput></term>
<listitem>
Stop soft instrumentation.
</listitem>
</varlistentry>

<varlistentry>
<term><computeroutput>nop</computeroutput></term>
<listitem>
Expand Down Expand Up @@ -1000,6 +1046,16 @@ The different possible actions are :
3) It is not possible to define <computeroutput>post-apply</computeroutput> action with <computeroutput>expect:</computeroutput>.
</listitem>
</varlistentry>
<varlistentry>
<listitem>
4) The use of <computeroutput>match:</computeroutput> and <computeroutput>expect:</computeroutput> with expressions which match the same line is not well defined.
</listitem>
</varlistentry>
<varlistentry>
<listitem>
5) This functionality is still experimental: naming may change and temporal part may be removed in a near future.
</listitem>
</varlistentry>
</variablelist>

</para>
Expand Down
4 changes: 2 additions & 2 deletions docs/vr-overview.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,7 @@ Type "help", "copyright", "credits" or "license" for more information.
<para>
This is for example the case of the douple-precision cosine implementation of the Gnu
mathematical library (<literal>libm</literal>). By default the libm is not instrumented, so to illustrate
the problem we add use the option <option><xref linkend="vr-opt.libm"/>=--libm=manual_exclude</option>.
the problem we add use the option <option><xref linkend="vr-opt.libm"/>=manual_exclude</option>.

Getting back to the previous python example:
</para>
Expand Down Expand Up @@ -215,7 +215,7 @@ Type "help", "copyright", "credits" or "license" for more information.
linkend="vr-manual.feat.exclude"/> for more details about exclusion lists.

But by doing this you are no able to measure the floating point error implied by <literal>libm</literal>. To pertub
libm we need to use the option <option><xref linkend="vr-opt.libm"/>=--libm=instrumentation</option>, which replace the dynamically loaded <literal>libm</literal> by your own
libm we need to use the option <option><xref linkend="vr-opt.libm"/>=instrumentation</option>, which replace the dynamically loaded <literal>libm</literal> by your own
stochastic implementation. If libm is statically linked with your application (Please don't do it), you will need to exclude yourself each <literal>libm</literal> symbol and it is not possible to measure floating point error implied by <literal>libm</literal>.
</para>
</section>
Expand Down
25 changes: 24 additions & 1 deletion docs/vr-scope.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,8 @@
When verrou finds a block of instructions (an IRSB, Intermediate Representation SuperBlock
in valgrind terminology) whose address matches the
<computeroutput>FNNAME</computeroutput>/<computeroutput>OBJNAME</computeroutput>
specification, the whole chunk is left uninstrumented.
specification, the whole chunk is left uninstrumented (we may still instrument IRSB to count
uninstrumented operations).
</para>

<warning>
Expand Down Expand Up @@ -319,6 +320,28 @@ int main () {
linkend="vr.monitor_instrumentation"/></computeroutput> monitor command.
</para>


<para>
As the <computeroutput>VERROU_START_INSTRUMENTATION</computeroutput> and <computeroutput>VERROU_STOP_INSTRUMENTATION</computeroutput> client requests (usually called hard stop/start) imply to flush the valgrind instrumentation cache, it can be expective for very frequent calls, we also propose an other couple of client requests (usually called soft sotp/start):
<computeroutput>VERROU_START_SOFT_INSTRUMENTATION</computeroutput> and <computeroutput>VERROU_STOP_SOFT_INSTRUMENTATION</computeroutput>. The idea behind is to instrument only once, but with a function which dynamically select between the instrumented backend and the nearest backend. As the instruemented code is less efficient, this approach designed only for frequent stop/start. The both approach are compatible : if <computeroutput>VERROU_STOP_SOFT_INSTRUMENTATION</computeroutput> or <computeroutput>VERROU_STOP_INSTRUMENTATION</computeroutput> are activated, the instrumentation is stopped.
</para>
<para>
The hard and soft stop/start can also be called (without recompilation) thanks the an expect script (See <option> <xref linkend="vr-opt.expect-clr"/></option>).
</para>
<para>
For python program it is possible to use python bindings:
<programlisting>
#!/usr/bin/python3
import valgrind.verrouPyBinding as verrou

verrou.start_instrumentation()
verrou.stop_instrumentation()
verrou.start_soft_instrumentation()
verrou.stop_soft_instrumentation()</programlisting>
</para>
<para>
As <computeroutput>verrou_dd_stdout</computeroutput> and <computeroutput>verrou_dd_task</computeroutput> use a stop/start mecanism (hard or soft), you can use the other mecanism to manually instrument your code, without unwanted side-effect.
</para>
</section>
</section>

Expand Down
3 changes: 2 additions & 1 deletion docs/vr-std.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,7 @@
<para>
Finally, the main use for Verrou is to randomly switch rounding mode at each floating-point
operation, in order to implement the "random rounding" variant of Monte Carlo Arithmetic
(MCA). Three strategies can be used to choose the rounding mode for a given operation:
(MCA). Several strategies can be used to choose the rounding mode for a given operation:
<itemizedlist>
<listitem><para><command>random:</command> Randomly pick one among upward and downward
rounding, with equal probabilities. This is a form of asynchronous CESTAC method.</para>
Expand Down Expand Up @@ -216,6 +216,7 @@
<listitem> fma(x,-y,-z) == -fma(x,y,z)</listitem>
<listitem> fma(x,y,0) == (x*y) </listitem>
<listitem> cast(-x) == -cast(x)</listitem>
<listitem> With <option><xref linkend="vr-opt.libm"/>=instrumented</option> the odd/even properties of libm instrumented functions are fullfilled. </listitem>
</itemizedlist>
</para>
</listitem>
Expand Down
1 change: 1 addition & 0 deletions vr_clo.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ void vr_env_clo(void){
vr_env_clo_one_option("VERROU_PRANDOM_UPDATE", "--prandom-update");
vr_env_clo_one_option("VERROU_PRANDOM_PVALUE", "--prandom-pvalue");
vr_env_clo_one_option("VERROU_INSTR_ATSTART", "--instr-atstart");
vr_env_clo_one_option("VERROU_INSTR_ATSTART_SOFT", "--instr-atstart-soft");
vr_env_clo_one_option("VERROU_EXCLUDE", "--exclude");
vr_env_clo_one_option("VERROU_GEN_EXCLUDE", "--gen-exclude");

Expand Down

0 comments on commit dfbbeb1

Please sign in to comment.