Adding description about using high performance decoder

and its options.
(Artur)

diff --git a/MUON/READMEraw.txt b/MUON/READMEraw.txt
index af99d735d68577299f4fa43bfc2821af633eae19..11d750bee358eca138cda70b3dab1742d80db74a 100644 (file)
--- a/MUON/READMEraw.txt
+++ b/MUON/READMEraw.txt
@@ -19,7 +19,6 @@ For tracker raw data, full output
 MUONRawStreamTrackerExpert(rawFileName, maxEvent, firstDDL, lastDDL)
 </pre>
 
-
 For tracker raw data, just digit output
 <pre>
 .includepath $ALICE_ROOT/STEER
@@ -29,6 +28,37 @@ For tracker raw data, just digit output
 MUONRawStreamTrackerSimple(rawFileName, maxEvent, firstDDL, lastDDL)
 </pre>
 
+There is also a high performance decoder available, which can be run as follows
+for full output:
+<pre>
+.includepath $ALICE_ROOT/STEER
+.includepath $ALICE_ROOT/MUON
+.includepath $ALICE_ROOT/RAW
+.L $ALICE_ROOT/MUON/MUONRawStreamTracker.C+
+MUONRawStreamTrackerHPExpert(rawFileName, maxEvent, firstDDL, lastDDL)
+</pre>
+
+And just for digit output like so:
+<pre>
+.includepath $ALICE_ROOT/STEER
+.includepath $ALICE_ROOT/MUON
+.includepath $ALICE_ROOT/RAW
+.L $ALICE_ROOT/MUON/MUONRawStreamTracker.C+
+MUONRawStreamTrackerHPSimple(rawFileName, maxEvent, firstDDL, lastDDL)
+</pre>
+
+The MUONRawStreamTracker.C macro also provides other alternative implementations
+for fetching the decoded data from the high performance decoder's interface.
+These generate the same output, but show how to write code to fetch the data in
+various ways from the interface. Developers should consult the macro as an example
+of how to use the interface. The alternate methods are called:
+<pre>
+MUONRawStreamTrackerHPExpert2()
+MUONRawStreamTrackerHPExpert3()
+MUONRawStreamTrackerHPSimple2()
+</pre>
+
+
 For trigger raw data, full output
 <pre>
 .includepath $ALICE_ROOT/STEER
@@ -75,6 +105,57 @@ data. The \em maxEvent value is the maximum event to process (default set to
 [0 .. maxEvent-1].
 
 
+\section raw_s3 Special flags for high performance tracker DDL decoder.
+
+There are three flags that are available through the AliMUONRawStreamTrackerHP
+interface, which effect the decoding of raw data in special ways.
+\li TryRecover
+\li AutoDetectTrailer
+\li CheckForTrailer
+
+The TryRecover flag is used to enable special logic in the decoder that tries
+to recover from a partially corrupt raw data structure header, or a corrupt/missing
+end of DDL trailer. Normally if the header is found to be corrupt (by seeing
+that the block lengths do not correspond),
+then the whole corresponding structure is skipped and we move on to the
+next structure that we are sure of, or skip the rest of the DDL.
+With the option to recover turned on, we attempt to figure out what the correct
+values for the structure length should have been. This is possible because there
+is redundant information in the headers giving the structure size. This recovery
+procedure will work for single bit flips found inside the headers, but obviously
+with more severe corruption, the header will not be recoverable.
+The TryRecover flag is set to kFALSE by default to disable this feature, meaning
+any structures in the raw data that cause problems in any way are skipped by
+default. More details about the corrupt header recovery procedure can be found
+in the method documentation AliMUONTrackerDDLDecoder::TryRecoverStruct().
+
+The AutoDetectTrailer and CheckForTrailer flags are used to deal with the
+difference in raw data format from the real tracker chambers and the simulated
+data generated with AliRoot up to March 2008. The end of DDL trailer words are
+missing in the simulated raw data in the older versions of AliRoot. To tell the
+decoder that it should expect the trailer words as generated by the real readout
+electronics then the CheckForTrailer flag should be set to kTRUE (this is the
+default). If the trailer words are missing in the raw data then CheckForTrailer
+should be kFALSE. Alternatively one can set the flag AutoDetectTrailer to kTRUE
+(which is the default) so that the decoder will try to autodetect if the trailer
+words are there or not. When AutoDetectTrailer is set to kTRUE then the
+CheckForTrailer flag is ignored. Only when AutoDetectTrailer is set to kFALSE
+will the CheckForTrailer flag have an effect.
+
+Each of these decoder flags can be set to kTRUE or kFALSE, or tested by the
+corresponding setter and getter methods respectively. For example, to set the
+TryRecover flag to kTRUE and fetch its value afterwards, use the following code:
+\code
+AliMUONRawStreamTrackerHP decoder;
+// to set the flag:
+decoder.TryRecover(kTRUE);
+// or to get the value of the flag:
+Bool_t value = decoder.TryRecover();
+\endcode
+Similarly, the other flags are manipulated with corresponding methods having
+the same name as the flag.
+
+
 This chapter is defined in the READMEraw.txt file.
 
 */