The R13B03 release.OTP_R13B03

1 files changed, 271 insertions, 0 deletions

diff --git a/lib/megaco/doc/src/megaco_debug.xml b/lib/megaco/doc/src/megaco_debug.xml
new file mode 100644
index 0000000000..1b99985341
--- /dev/null
+++ b/lib/megaco/doc/src/megaco_debug.xml
@@ -0,0 +1,271 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2000</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>Testing and tools</title>
+    <prepared>H&aring;kan Mattsson</prepared>
+    <responsible>H&aring;kan Mattsson</responsible>
+    <docno></docno>
+    <approved>H&aring;kan Mattsson</approved>
+    <checked></checked>
+    <date>2007-06-15</date>
+    <rev>%VSN%</rev>
+    <file>megaco_debug.xml</file>
+  </header>
+
+  <section>
+    <title>Tracing</title>
+    <p>We have instrumented our code in order to enable
+      tracing. Running the application with tracing deactivated,
+      causes a negligible performance overhead (an external call to a
+      function which returns an atom). Activation of tracing does not
+      require any recompilation of the code, since we rely on
+      Erlang/OTP's built in support for dynamic trace activation. In
+      our case tracing of calls to a given external function.</p>
+    <p>Event traces can be viewed in a generic message sequence chart
+      tool, <c>et</c>, or as standard output (events are written to stdio). </p>
+    <p>See <seealso marker="megaco#enable_trace">enable_trace</seealso>, 
+      <seealso marker="megaco#disable_trace">disable_trace</seealso> and
+      <seealso marker="megaco#set_trace">set_trace</seealso> for
+      more info. </p>
+  </section>
+
+  <section>
+    <title>Measurement and transformation</title>
+    <p>We have included some simple tool(s) for codec measurement (meas),
+      performance tests (mstone1 and mstone2) and message transformation.</p>
+    <p>The tool(s) are located in the example/meas directory.</p>
+
+    <section>
+      <title>Requirement</title>
+      <list type="bulleted">
+        <item>
+          <p>Erlang/OTP, version R13B01 or later.</p>
+        </item>
+        <item>
+          <p>Version 3.11 or later of <em>this</em> application.</p>
+        </item>
+        <item>
+          <p>Version 1.6.10 or later of the <em>asn1</em> application. </p>
+        </item>
+        <item>
+          <p>The flex libraries. Without it, the flex powered codecs cannot 
+            be used.</p>
+        </item>
+      </list>
+    </section>
+
+    <section>
+      <title>Meas results</title>
+      <p>The results from the measurement run (meas) is four 
+        excel-compatible textfiles: </p>
+      <list type="bulleted">
+        <item>
+          <p>decode_time.xls  -&gt; Decoding result</p>
+        </item>
+        <item>
+          <p>encode_time.xls  -&gt; Encoding result</p>
+        </item>
+        <item>
+          <p>total_time.xls   -&gt; Total (Decoding+encoding) result</p>
+        </item>
+        <item>
+          <p>message_size.xls -&gt; Message size</p>
+        </item>
+      </list>
+    </section>
+
+    <section>
+      <title>Instruction</title>
+      <p>The tool contain four things:
+        </p>
+      <list type="bulleted">
+        <item>
+          <p>The transformation module</p>
+        </item>
+        <item>
+          <p>The measurement (meas) module(s)</p>
+        </item>
+        <item>
+          <p>The mstone (mstone1 and mstone2) module(s)</p>
+        </item>
+        <item>
+          <p>The basic message file</p>
+        </item>
+      </list>
+
+      <section>
+        <title>Message Transformation</title>
+        <p>The messages used by the different tools are contained in 
+          single message package file (see below for more info). The messages
+          in this file is encoded with just one codec. During 
+          measurement initiation, the messages are read and then transformed to all
+          codec formats used in the measurement. </p>
+        <p>The message transformation is done by the transformation module.
+          It is used to transform a set of messages encoded with one codec 
+          into the other base codec's.</p>
+      </section>
+
+      <section>
+        <title>Measurement(s)</title>
+        <p>There are two different measurement tools: </p>
+        <list type="bulleted">
+          <item>
+            <p><em>meas</em>: </p>
+            <p>Used to perform codec measurements. That is, to see what 
+              kind of performance can be expected by the different codecs 
+              provided by the megaco application. </p>
+            <p>The measurement is done by iterating over the decode/encode 
+              function for approx 2 seconds per message and counting 
+              the number of decodes/encodes.</p>
+            <p>Is best run by modifying the meas.sh.skel skeleton script
+              provided by the tool.</p>
+            <p>To run it manually do the following: </p>
+              <code type="none"><![CDATA[
+        % erl -pa <path-megaco-ebin-dir> -pa <path-to-meas-module-dir>
+        Erlang (BEAM) emulator version 5.6 [source]
+
+        Eshell V5.7.1  (abort with ^G)
+        1> megaco_codec_meas:start().
+        ...
+        2> halt().
+        ]]></code>
+            <p>or to make it even easier, assuming a measure shall be 
+              done on all the codecs (as above):</p>
+              <code type="none"><![CDATA[
+        % erl -noshell -pa <path-megaco-ebin-dir> \\
+              -pa <path-to-meas-module-dir> \\
+              -s megaco_codec_meas -s init stop
+        ]]></code>
+            <p>When run as above (this will take some time), the measurement 
+              process is done as follows:</p>
+        <pre>
+\011  For each codec:
+\011      For each message:
+\011          Read the message from the file
+\011               Detect message version
+\011               Measure decode
+                       Measure encode
+          Write results, encode, decode and total, to file
+        </pre>
+          </item>
+
+          <item>
+            <p><em>mstone1 and mstone2</em>: </p>
+            <p>These are two different SMP performance monitoring tool(s). </p>
+            <p><em>mstone1</em> creates a process for each codec config supported by 
+              the megaco application and let them run for a specific 
+              time (all at the same time), encoding and decoding 
+              megaco messages. The number of messages processed in total 
+              is the mstone1(1) value. </p>
+            <p>There are different ways to run the mstone1 tool, e.g. with or without 
+              the use of drivers, with <em>only</em> flex-empowered configs. </p>
+            <p>Is best run by modifying the mstone1.sh.skel skeleton script
+              provided by the tool.</p>
+            <p>The <em>mstone2</em> is similar to the <em>mstone1</em> tool,
+              but in this case, each created process makes only <em>one</em> run 
+              through the messages and then exits. A soon as a process exits,
+              a new process (with the same config and messages) is created to takes 
+              its place. 
+              The number of messages processed in total 
+              is the mstone2(1) value. </p>
+          </item>
+        </list>
+
+        <p>Both these tools use the message package (time_test.msgs) provided
+          with the tool(s), although it can run on any message package as long as
+          it has the same structure. </p>
+      </section>
+
+      <section>
+        <title>Message package file</title>
+        <p>This is simply an erlang compatible text-file with the following 
+          structure: <c>{codec_name(), messages_list()}</c>. </p>
+
+<pre>
+codec_name() = pretty | compact | ber | per | erlang      (how the messages are encoded)
+messages_list() = [{message_name(), message()}]
+message_name() = atom()
+message() = binary()
+</pre>
+
+        <p>The codec name is the name of the codec with which all messages in
+          the <c>message_list()</c> has been encoded. </p>
+
+        <p>This file can be <c>exported</c> to a file structure by calling the 
+          <seealso marker="megaco_codec_transform#export_messages">export_messages</seealso>
+          function. This can be usefull if a measurement shall be done with
+          an external tool. Exporting the messages creates a directory tree 
+          with the following structure:
+          </p>
+        <code type="none"><![CDATA[
+\011  <message package>/pretty/<message-files>
+\011                    compact/
+\011                    per/
+\011                    ber/<message-files>
+\011                    erlang/
+        ]]></code>
+        <p>The file includes both version 1, 2 and version 3 messages.</p>
+      </section>
+    </section>
+
+    <section>
+      <title>Notes</title>
+
+      <section>
+        <title>Binary codecs</title>
+        <p>There are two basic ways to use the binary encodings: 
+          With package related name and termination id transformation
+          (the 'native' encoding config) or without. This transformation 
+          converts package related names and termination id's to a more 
+          convenient internal form (equivalent with the decoded text message).</p>
+        <p>The transformation is done _after_ the actual decode has been 
+          done.</p>
+        <p>Furthermore, it is possible to make use of a linked in driver that 
+          performs some of the decode/encode, decode for ber and encode for per 
+          (the 'driver' encoding config).</p>
+        <p>Therefor in the tests, binary codecs are tested with four 
+          different encoding configs to determine exactly how the
+          different options effect the performance: with transformation and 
+          without driver ([]), without transformation and without driver 
+          ([native]), with transformation and with driver ([driver]) and 
+          finally without transformation and with driver ([driver,native]).</p>
+      </section>
+
+      <section>
+        <title>Included test messages</title>
+        <p>Some of these messages are ripped from the call flow examples 
+          in an old version of the RFC and others are created to test
+          a specific feature of megaco. </p>
+      </section>
+
+      <section>
+        <title>Measurement tool directory name</title>
+        <p>Be sure <em>not</em> no name the directory containing the measurement
+          binaries starting with 'megaco-', e.g. megaco-meas. This will
+          confuse the erlang application loader (erlang applications
+          are named, e.g. megaco-1.0.2).</p>
+      </section>
+    </section>
+  </section>
+</chapter>
+