Write only detector coefficients from HLT (Raphaelle)
[u/mrichter/AliRoot.git] / MUON / AliMUONTriggerDDLDecoder.h
1 #ifndef ALIMUONTRIGGERDDLDECODER_H
2 #define ALIMUONTRIGGERDDLDECODER_H
3 /**************************************************************************
4  * This file is property of and copyright by the ALICE HLT Project        *
5  * All rights reserved.                                                   *
6  *                                                                        *
7  * Primary Authors:                                                       *
8  *   Artur Szostak <artursz@iafrica.com>                                  *
9  *                                                                        *
10  * Permission to use, copy, modify and distribute this software and its   *
11  * documentation strictly for non-commercial purposes is hereby granted   *
12  * without fee, provided that the above copyright notice appears in all   *
13  * copies and that both the copyright notice and this permission notice   *
14  * appear in the supporting documentation. The authors make no claims     *
15  * about the suitability of this software for any purpose. It is          *
16  * provided "as is" without express or implied warranty.                  *
17  **************************************************************************/
18
19 /* $Id$ */
20
21 ///
22 /// \file   AliMUONTriggerDDLDecoder.h
23 /// \author Artur Szostak <artursz@iafrica.com>
24 /// \date   28-11-2007
25 /// \brief  Implementation of a high performance DDL decoder for the muon trigger.
26 ///
27 /// This file implementes the AliMUONTriggerDDLDecoder class, which contains
28 /// the core logic for decoding the payload in DDL streams comming from the muon
29 /// spectrometer's hardware trigger in a very efficient manner.
30 ///
31 /// This implementation is derived from work done by Christian Finck for the
32 /// AliMUONPayloadTrigger class.
33 ///
34 /// Note to maintainers: Please remember that this file is used by the online
35 /// dHLT system. As an online system, the dHLT requires the fastest code possible
36 /// in the decoders to satisfy its timing constraints. The performance impact
37 /// must be checked before any proposed modification is made to this file.
38 ///
39
40 #include "AliMUONTriggerDDLDecoderEventHandler.h"
41
42 /// \ingroup raw
43 /// \class AliMUONTriggerDDLDecoder
44 /// \brief A high performance decoder class for MUON trigger DDL data.
45 ///
46 /// This class implements a high performance decoder for decoding DDL payload
47 /// data coming from the muon spectrometers trigger stations.
48 /// It has been implemented using the event driven paradigm with templates,
49 /// which allows us to minimise the number of method calls made in the inner
50 /// loops of the algorithm and minimise the memory footprint.
51 /// At least for optimised production compilations.
52 /// The decoder class only contains the basic decoding and error checking logic.
53 /// It calls methods such as OnNewBuffer, OnDarcHeader, OnNewRegionalStruct,
54 /// OnLocalStruct etc in the event handler during the decoding to return the
55 /// decoded data and headers.
56 /// The event handler class is nothing more than a callback interface to deliver
57 /// the next chunks of decoded data.
58 /// To actually do something with the data, one needs to implement a custom
59 /// event handler (callback) class by inheriting from AliMUONTriggerDDLDecoderEventHandler
60 /// and overriding the callback methods like so:
61 /// \code
62 ///  class MyCustomHandler : public AliMUONTriggerDDLDecoderEventHandler
63 ///  {
64 ///  public:
65 ///     void OnLocalStruct(const AliMUONLocalInfoStruct* localStruct,
66 ///                        const AliMUONLocalScalarsStruct* scalars)
67 ///     {
68 ///       // I can do something with the data in 'localStruct' here.
69 ///       // and the 'scalars' if they are not NULL.
70 ///     }
71 ///  };
72 /// \endcode
73 ///
74 /// Once the custom handler is written then the decoder is instantiated as
75 /// shown below, to use your new custom handler. Also to start decoding one needs
76 /// to call the Decode() method of the decoder.
77 /// \code
78 ///  AliMUONTriggerDDLDecoder<MyCustomHandler> myDecoder;
79 ///  muDecoder.Decoder(buffer, bufferSize);
80 /// \endcode
81 ///
82 /// Note that this class was written as a template on purpose. To maximise the
83 /// compilers chance to make optimisations and inline the code we must use a template.
84 /// Depending on exactly what you do inside your handler, the decoder could be
85 /// significantly slower if run time polymorphism was used, i.e. making the class
86 /// AliMUONTriggerDDLDecoderEventHandler abstract and using virtual methods.
87 ///
88 template <class EventHandler>
89 class AliMUONTriggerDDLDecoder
90 {
91 public:
92
93         /// Default contructor.
94         AliMUONTriggerDDLDecoder() :
95                 fExitOnError(true), fTryRecover(false),
96                 fAutoDetectScalars(false), fHadError(false),
97                 fNoRegionals(0), fMaxRegionals(8), fMaxLocals(16),
98                 fHandler()
99         {}
100         
101         /// Constant method to return the event handler instance.
102         const EventHandler& GetHandler() const { return fHandler; }
103         
104         /// Returns the event handler instance.
105         EventHandler& GetHandler() { return fHandler; }
106         
107         /// Returns the "exit on error" flag.
108         /// i.e. should the decoder stop on the very first error found.
109         bool ExitOnError() const { return fExitOnError; }
110         
111         /// Sets the "exit on error" flag.
112         /// i.e. should the decoder stop on the very first error found.
113         void ExitOnError(bool value) { fExitOnError = value; }
114         
115         /// Returns the "try to recover from errors" flag.
116         /// i.e. should the decoder try to recover from errors found in the
117         /// payload headers.
118         bool TryRecover() const { return fTryRecover; }
119         
120         /// Sets the "try to recover from errors" flag.
121         /// i.e. should the decoder try to recover from errors found in the
122         /// payload headers.
123         void TryRecover(bool value) { fTryRecover = value; }
124         
125         /// Returns the flag indicating if we should check for the scalars of
126         /// software triggers automatically or not.
127         bool AutoDetectScalars() const { return fAutoDetectScalars; }
128         
129         /// Sets the flag indicating if we should check for the scalars of
130         /// software triggers automatically or not. If set to true then the
131         /// scalarEvent parameter of the Decode method is ignored.
132         void AutoDetectScalars(bool value) { fAutoDetectScalars = value; }
133         
134         /// Returns the maximum regional structure count expected in the DDL payload.
135         UInt_t MaxRegionals() const { return fMaxRegionals; }
136         
137         /// Sets the maximum regional structure count expected in the DDL payload.
138         void MaxRegionals(UInt_t n) { fMaxRegionals = n; }
139         
140         /// Returns the number of regional structures we actually attempted to decode.
141         UInt_t RegionalsDecoded() const { return fNoRegionals; }
142         
143         /// Returns the maximum local structure count expected in any given regional
144         /// card structure within the DDL payload.
145         UInt_t MaxLocals() const { return fMaxLocals; }
146         
147         /// Sets the maximum local structure count expected in any given regional
148         /// card structure within the DDL payload.
149         void MaxLocals(UInt_t n) { fMaxLocals = n; }
150         
151         /// This method decodes the DDL payload contained in the buffer.
152         bool Decode(const void* buffer, UInt_t bufferSize, bool scalarEvent = false);
153         
154         /// Returns the end of DARC marker key.
155         static UInt_t EndOfDarcWord() { return fgkEndOfDarc; }
156         
157         /// Returns the end of global header marker key.
158         static UInt_t EndOfGlobalWord() { return fgkEndOfGlobal; }
159         
160         /// Returns the end of regional structure marker key.
161         static UInt_t EndOfRegionalWord() { return fgkEndOfReg; }
162         
163         /// Returns the regional error word.
164         static UInt_t RegionalErrorWord() { return fgkErrorWord; }
165         
166         /// Returns the end of local structure marker key.
167         static UInt_t EndOfLocalWord() { return fgkEndOfLocal; }
168         
169         /// Returns the local card disable word.
170         static UInt_t LocalDisableWord() { return fgkDisableWord; }
171         
172         /// Returns value of default DARC type.
173         static UInt_t DarcDefaultType() { return fgkDarcDefaultType; }
174         
175         /// Returns value of Vadorh DARC type.
176         static UInt_t DarcVadorhType()  { return fgkDarcVadorhType; }
177         
178 private:
179
180         bool fExitOnError; ///< Indicates if we should exit on the very first error.
181         bool fTryRecover; ///< Indicates if we should try recover from a corrupt structures.
182         bool fAutoDetectScalars; ///< Flag to indicate if we should auto-detect if there are scalars in the data.
183         bool fHadError; ///< Indicates if we had an error decoding the data.
184         UInt_t fNoRegionals; ///< The number of regional card structures actually decoded.
185         UInt_t fMaxRegionals; ///< Maximum number of regional card structures allowed in a DDL stream.
186         UInt_t fMaxLocals; ///< Maximum number of local card structures per regional structure allowed in a DDL stream.
187         EventHandler fHandler; ///< The event handler which deals with the generated parsing events.
188
189         void DecodeBuffer(const UChar_t* start, const UChar_t* end, bool scalarEvent);
190         void DecodeRegionalStructs(const UChar_t* start, const UChar_t* end, bool scalarEvent);
191         const UChar_t* DecodeLocalStructs(const UChar_t* start, const UChar_t* end, bool scalarEvent);
192         
193         const UChar_t* FindKey(
194                         UInt_t key, const UChar_t* start, const UChar_t* end
195                 );
196
197         static const UInt_t fgkEndOfDarc;   ///< Indicates the end of the DARC header.
198         static const UInt_t fgkEndOfGlobal; ///< Indicates the end of the global header just after the DARC header.
199         static const UInt_t fgkEndOfReg;    ///< Indicates the end of a regional card structure.
200         static const UInt_t fgkErrorWord;   ///< The error word when a regional board is missing.
201         static const UInt_t fgkEndOfLocal;  ///< Indicates the end of a local card structure.
202         static const UInt_t fgkDisableWord; ///< Word used to fill "empty" slots.
203         static const UInt_t fgkDarcDefaultType;   ///< default type for DARC def.
204         static const UInt_t fgkDarcVadorhType;    ///< default type for DARC vadorh
205 };
206
207 //_____________________________________________________________________________
208
209 // The following are the structure key words which are used to demarcate (identify
210 // the end) of the structures within the raw trigger data.
211 template <class EventHandler>
212 const UInt_t AliMUONTriggerDDLDecoder<EventHandler>::fgkEndOfDarc    = 0xDEADFACE;
213 template <class EventHandler>
214 const UInt_t AliMUONTriggerDDLDecoder<EventHandler>::fgkEndOfGlobal  = 0xDEADBEEF;
215 template <class EventHandler>
216 const UInt_t AliMUONTriggerDDLDecoder<EventHandler>::fgkEndOfReg     = 0xBEEFFACE;
217 template <class EventHandler>
218 const UInt_t AliMUONTriggerDDLDecoder<EventHandler>::fgkErrorWord    = 0xCAFEDEAD;
219 template <class EventHandler>
220 const UInt_t AliMUONTriggerDDLDecoder<EventHandler>::fgkEndOfLocal   = 0xCAFEFADE;
221 template <class EventHandler>
222 const UInt_t AliMUONTriggerDDLDecoder<EventHandler>::fgkDisableWord  = 0x10CADEAD;
223 template <class EventHandler>
224 const UInt_t AliMUONTriggerDDLDecoder<EventHandler>::fgkDarcDefaultType = 0x6;
225 template <class EventHandler>
226 const UInt_t AliMUONTriggerDDLDecoder<EventHandler>::fgkDarcVadorhType  = 0x4;
227
228
229 template <class EventHandler>
230 bool AliMUONTriggerDDLDecoder<EventHandler>::Decode(
231                 const void* buffer, UInt_t bufferSize, bool scalarEvent
232         )
233 {
234         /// This method should be called to actually decode the DDL payload
235         /// contained in a memory buffer. The payload should be in the muon trigger
236         /// system DDL stream format otherwise it will be recognised as corrupt.
237         /// As the decoder progresses it will make method calls to the event handler
238         /// instance (which can be accessed with the GetHandler() method) to indicate
239         /// the start of the DARC header, global header, new regional structures and
240         /// local card structures.
241         ///
242         /// If an error occurs during the parse, because the data is corrupt, then
243         /// the OnError method is called indicating what the problem was.
244         /// Decoding will stop at this point unless the fExitOnError flag is set
245         /// to false. There is an optional flag fTryRecover which can enable logic
246         /// which will attempt to recover from corruption of the data structures
247         /// in the DDL payload, if they are found to be inconsistent (assumed corrupt).
248         /// The recovery procedure simply involves trying to find in the DDL stream
249         /// the location of the expected end of header/structure marker/key or the
250         /// next expected key, and then continue decoding from there. This kind of
251         /// recovery logic is (and should be) turned off by default and only
252         /// enabled when trying to recover corrupted data.
253         ///
254         /// \param buffer  This is the pointer to the start of the memory buffer
255         ///     containing the DDL payload. Remember that this must be the start of
256         ///     the payload and not the DDL stream. That is, this pointer should be
257         ///     equal to: DDL start pointer + 8 * sizeof(UInt_t).
258         /// \param bufferSize  This is the pointer to the first byte just past the
259         ///     end of the block structure.
260         /// \param scalarEvent  Set to true if this DDL contains a scalar event
261         ///     and false if it is a normal physics event. If the fAutoDetectScalars
262         ///     flag is true then we ignore this parameter.
263         /// \return Returns false if there was any problem with decoding the data,
264         ///     and true otherwise. Note: the data may have been partially decoded
265         ///     even if false was returned, which would be indicated by at least one
266         ///     call to the event handler's OnLocalStruct or OnNewRegionalStruct methods.
267         
268         assert( buffer != NULL );
269         
270         fHadError = false;
271         
272         // We are basically implementing something like a recursive decent parser.
273         // So start by marking the start of buffer position and end of buffer.
274         const UChar_t* start = reinterpret_cast<const UChar_t*>(buffer);
275         const UChar_t* end = start + bufferSize;
276         
277         fHandler.OnNewBuffer(buffer, bufferSize);
278         DecodeBuffer(start, end, scalarEvent);
279         fHandler.OnEndOfBuffer(buffer, bufferSize);
280         return not fHadError;
281 }
282
283
284 template <class EventHandler>
285 void AliMUONTriggerDDLDecoder<EventHandler>::DecodeBuffer(
286                 const UChar_t* start, const UChar_t* end, bool scalarEvent
287         )
288 {
289         /// This method does the work to decode the buffer's payload data. It
290         /// unpacks the DARC header, the global header, then calls the
291         /// DecodeRegionalStructs() method to decode the regional structures.
292         /// For the DARC and global headers the methods OnDarcHeader and
293         /// OnGlobalHeader of the event handler object are called respectively.
294         /// \param start  This is the pointer to the start of the buffer to decode.
295         /// \param end  This is the pointer to the first byte just past the
296         ///             end of the buffer.
297         /// \param scalarEvent  Set to true if this DDL contains a scalar event
298         ///     and false if it is a normal physics event.
299         ///
300         /// fHadError is set to true if there were any errors decoding the buffer
301         /// and the OnError method of the callback event handler is called for
302         /// each error.
303         
304         const UChar_t* current = start;
305         
306         // Mark the DARC header, but check that we do not overrun the buffer.
307         const UInt_t* darcHeader = reinterpret_cast<const UInt_t*>(current);
308         current += sizeof(UInt_t);
309         if (current > end or current < start)
310         {
311                 // Indicate we had an error and stop the decoding because we
312                 // hit the end of the buffer already.
313                 fHandler.OnError(EventHandler::kNoDarcHeader, darcHeader);
314                 fHadError = true;
315                 return;
316         }
317         
318         // Check if we need to figure out if this is a scalar event.
319         // If we do, then we do this by checking the event type in the DARC header
320         // and double checking this by checking if the fgkEndOfDarc key is in the
321         // expected location for a scalar event DDL payload.
322         if (fAutoDetectScalars)
323         {
324                 const UInt_t* expectedEndOfDarc = reinterpret_cast<const UInt_t*>(
325                                 current + sizeof(AliMUONDarcScalarsStruct)
326                         );
327                 
328                 // First make sure not to read past the end of buffer. Then check
329                 // the value of the event type in the DARC header.
330                 // Physics events are indicated by the two trigger bits of the
331                 // DARC header set to 01b. Everything else is a software trigger
332                 // of some sort.
333                 if (reinterpret_cast<const UChar_t*>(expectedEndOfDarc+1) <= end and
334                     reinterpret_cast<const UChar_t*>(expectedEndOfDarc+1) > start and
335                     EventHandler::GetDarcEventType(*darcHeader) != 0x1
336                     and *expectedEndOfDarc == fgkEndOfDarc
337                    )
338                 {
339                         scalarEvent = true;
340                 }
341                 else
342                 {
343                         scalarEvent = false;
344                 }
345         }
346         
347         // Detect how many regional blocks we expect. If we have no idea then
348         // just use what the maximum setting is.
349         UInt_t darkType = EventHandler::GetDarcType(*darcHeader);
350         if (darkType == fgkDarcVadorhType)
351         {
352                 fNoRegionals = 1;
353         }
354         else if (darkType == fgkDarcDefaultType)
355         {
356                 fNoRegionals = 8;
357         }
358         else
359         {
360                 fNoRegionals = fMaxRegionals;
361         }
362         
363         // Check if the DARC header indicates we expect more regionals than we
364         // are allowed to decode according to our max regional structures count.
365         // If we do then this is an error and we should indicate it and exit
366         // if so requested by the user. Also we can fix the number of regionals
367         // to expect if we are trying to recover from errors.
368         if (fNoRegionals > fMaxRegionals)
369         {
370                 fHandler.OnError(EventHandler::kTooManyRegionals, darcHeader);
371                 fHadError = true;
372                 if (fExitOnError) return;
373                 if (fTryRecover)
374                 {
375                         fNoRegionals = fMaxRegionals;
376                 }
377         }
378         
379         // Check that the DARC header indicates correctly if we are a scalar event or not.
380         bool darcShowsScalar = (EventHandler::GetDarcEventType(*darcHeader) != 0x1);
381         if (darcShowsScalar != scalarEvent)
382         {
383                 // Indicate we had an error and stop the decoding if so requested
384                 // by the user.
385                 fHandler.OnError(EventHandler::kWrongEventType, darcHeader);
386                 fHadError = true;
387                 if (fExitOnError) return;
388         }
389         
390         // Decode the DARC scalars if this is a scalar event.
391         const AliMUONDarcScalarsStruct* darcScalars = NULL;
392         if (scalarEvent)
393         {
394                 darcScalars = reinterpret_cast<const AliMUONDarcScalarsStruct*>(current);
395                 current += sizeof(AliMUONDarcScalarsStruct);
396                 if (current > end or current < start)
397                 {
398                         // If we overflowed the pointer and already had an error then
399                         // we are clearly lost so just stop decoding before we segfault.
400                         if (current < start and fHadError) return;
401                         
402                         // Indicate we had an error and stop the decoding because we
403                         // hit the end of the buffer already.
404                         fHandler.OnError(EventHandler::kNoDarcScalars, darcScalars);
405                         fHadError = true;
406                         return;
407                 }
408         }
409         
410         // Now check that the end of DARC header marker is OK.
411         const UInt_t* endOfDarc = reinterpret_cast<const UInt_t*>(current);
412         current += sizeof(UInt_t);
413         if (current > end or current < start)
414         {
415                 // If we overflowed the pointer and already had an error then
416                 // we are clearly lost so just stop decoding before we segfault.
417                 if (current < start and fHadError) return;
418                 
419                 // Indicate we had an error and stop the decoding because we
420                 // hit the end of the buffer already.
421                 fHandler.OnError(EventHandler::kNoEndOfDarc, endOfDarc);
422                 fHadError = true;
423                 return;
424         }
425         if (*endOfDarc != fgkEndOfDarc)
426         {
427                 // Indicate we had an error and stop the decoding if so requested
428                 // by the user.
429                 fHandler.OnError(EventHandler::kBadEndOfDarc, endOfDarc);
430                 fHadError = true;
431                 if (fExitOnError) return;
432                 
433                 // If the user requested for us to try and recover from structure
434                 // errors then we need to try locate the key in the data stream
435                 // and continue decoding from there.
436                 if (fTryRecover)
437                 {
438                         const UChar_t* keypos = FindKey(fgkEndOfDarc,
439                                         reinterpret_cast<const UChar_t*>(darcHeader),
440                                         end
441                                 );
442                         if (keypos != NULL)
443                         {
444                                 // remember to continue decoding just past the key.
445                                 current = keypos + sizeof(UInt_t);
446                         }
447                 }
448         }
449         
450         fHandler.OnDarcHeader(*darcHeader, darcScalars, current);
451         
452         // Next, we mark the Global header and check that we do not overrun the buffer.
453         const AliMUONGlobalHeaderStruct* globalHeader =
454                 reinterpret_cast<const AliMUONGlobalHeaderStruct*>(current);
455         current += sizeof(AliMUONGlobalHeaderStruct);
456         if (current > end or current < start)
457         {
458                 // If we overflowed the pointer and already had an error then
459                 // we are clearly lost so just stop decoding before we segfault.
460                 if (current < start and fHadError) return;
461                 
462                 // Indicate we had an error and stop the decoding because we
463                 // hit the end of the buffer already.
464                 fHandler.OnError(EventHandler::kNoGlobalHeader, globalHeader);
465                 fHadError = true;
466                 return;
467         }
468         
469         // Decode the global scalars if this is a scalar event.
470         const AliMUONGlobalScalarsStruct* globalScalars = NULL;
471         if (scalarEvent)
472         {
473                 globalScalars = reinterpret_cast<const AliMUONGlobalScalarsStruct*>(current);
474                 current += sizeof(AliMUONGlobalScalarsStruct);
475                 if (current > end or current < start)
476                 {
477                         // If we overflowed the pointer and already had an error then
478                         // we are clearly lost so just stop decoding before we segfault.
479                         if (current < start and fHadError) return;
480                         
481                         // Indicate we had an error and stop the decoding because we
482                         // hit the end of the buffer already.
483                         fHandler.OnError(EventHandler::kNoGlobalScalars, globalScalars);
484                         fHadError = true;
485                         return;
486                 }
487         }
488         
489         // Now check that the end of global header marker is OK.
490         const UInt_t* endOfGlobal = reinterpret_cast<const UInt_t*>(current);
491         current += sizeof(UInt_t);
492         if (current > end or current < start)
493         {
494                 // If we overflowed the pointer and already had an error then
495                 // we are clearly lost so just stop decoding before we segfault.
496                 if (current < start and fHadError) return;
497                 
498                 // Indicate we had an error and stop the decoding because we
499                 // hit the end of the buffer already.
500                 fHandler.OnError(EventHandler::kNoEndOfGlobal, endOfGlobal);
501                 fHadError = true;
502                 return;
503         }
504         if (*endOfGlobal != fgkEndOfGlobal)
505         {
506                 // Indicate we had an error and stop the decoding if so requested
507                 // by the user.
508                 fHandler.OnError(EventHandler::kBadEndOfGlobal, endOfGlobal);
509                 fHadError = true;
510                 if (fExitOnError) return;
511                 
512                 // If the user requested for us to try and recover from structure
513                 // errors then we need to try locate the key in the data stream
514                 // and continue decoding from there.
515                 if (fTryRecover)
516                 {
517                         const UChar_t* keypos = FindKey(fgkEndOfGlobal,
518                                         reinterpret_cast<const UChar_t*>(globalHeader),
519                                         end
520                                 );
521                         if (keypos != NULL)
522                         {
523                                 // remember to continue decoding just past the key.
524                                 current = keypos + sizeof(UInt_t);
525                         }
526                 }
527         }
528         
529         fHandler.OnGlobalHeader(globalHeader, globalScalars, current);
530         
531         DecodeRegionalStructs(current, end, scalarEvent);
532 }
533
534
535 template <class EventHandler>
536 void AliMUONTriggerDDLDecoder<EventHandler>::DecodeRegionalStructs(
537                 const UChar_t* start, const UChar_t* end, bool scalarEvent
538         )
539 {
540         /// This method decodes the regional structures in the DDL data.
541         /// For each regional header found, the OnNewRegionalStruct method of
542         /// the event handler is called, to signal the start of each
543         /// new regional structure. The DecodeLocalStructs() method is then
544         /// called to decode the local trigger structures. Finally, a symmetrical
545         /// call to OnEndOfRegionalStruct of the event handler is called to
546         /// signal that the regional structure has been decoded.
547         /// \param start  This is the pointer to the start of the buffer.
548         /// \param end  This is the pointer to the first byte just past the
549         ///             end of the buffer.
550         /// \param scalarEvent  Set to true if this DDL contains a scalar event
551         ///     and false if it is a normal physics event.
552         ///
553         /// fHadError is set to true if there were any errors decoding the buffer
554         /// and the OnError method of the callback event handler is called for
555         /// each error.
556         
557         const UChar_t* current = start;
558         
559         for (UInt_t iReg = 0; iReg < fNoRegionals; iReg++)
560         {
561                 const AliMUONRegionalHeaderStruct* regionalHeader =
562                         reinterpret_cast<const AliMUONRegionalHeaderStruct*>(current);
563                 current += sizeof(AliMUONRegionalHeaderStruct);
564                 
565                 if (current > end or current < start)
566                 {
567                         // If we overflowed the pointer and already had an error then
568                         // we are clearly lost so just stop decoding before we segfault.
569                         if (current < start and fHadError) return;
570                         
571                         // So we only got part of a regional header, nothing to do but
572                         // report the error and exit.
573                         fHandler.OnError(EventHandler::kNoRegionalHeader, regionalHeader);
574                         fHadError = true;
575                         return;
576                 }
577                 
578                 // Skip empty regional board (not connected or with error reading).
579                 if (regionalHeader->fDarcWord == fgkErrorWord)
580                 {
581                         //current += sizeof(AliMUONRegionalHeaderStruct);  // already done above
582                         if (scalarEvent)
583                                 current += sizeof(AliMUONRegionalScalarsStruct);
584                         current += sizeof(UInt_t); // skip the end of regional structure key.
585                         
586                         // now also skip the local structure part:
587                         current += fMaxLocals * sizeof(AliMUONLocalInfoStruct);
588                         if (scalarEvent)
589                                 current += fMaxLocals * sizeof(AliMUONLocalScalarsStruct);
590                         current += fMaxLocals * sizeof(UInt_t); // skip all the end of local structure keys.
591                         
592                         continue;
593                 }
594                 
595                 // Decode the regional scalar words if this is a scalar event.
596                 const AliMUONRegionalScalarsStruct* regionalScalars = NULL;
597                 if (scalarEvent)
598                 {
599                         regionalScalars = reinterpret_cast<const AliMUONRegionalScalarsStruct*>(current);
600                         current += sizeof(AliMUONRegionalScalarsStruct);
601                         if (current > end or current < start)
602                         {
603                                 // If we overflowed the pointer and already had an error then
604                                 // we are clearly lost so just stop decoding before we segfault.
605                                 if (current < start and fHadError) return;
606                                 
607                                 // Indicate we had an error and stop the decoding because we
608                                 // hit the end of the buffer already.
609                                 fHandler.OnError(EventHandler::kNoRegionalScalars, regionalScalars);
610                                 fHadError = true;
611                                 return;
612                         }
613                 }
614                 
615                 // Now check that the end of regional header marker is OK.
616                 const UInt_t* endOfRegional = reinterpret_cast<const UInt_t*>(current);
617                 current += sizeof(UInt_t);
618                 if (current > end or current < start)
619                 {
620                         // If we overflowed the pointer and already had an error then
621                         // we are clearly lost so just stop decoding before we segfault.
622                         if (current < start and fHadError) return;
623                         
624                         // Indicate we had an error and stop the decoding because we
625                         // hit the end of the buffer already.
626                         fHandler.OnError(EventHandler::kNoEndOfRegional, endOfRegional);
627                         fHadError = true;
628                         return;
629                 }
630                 if (*endOfRegional != fgkEndOfReg)
631                 {
632                         // Indicate we had an error and stop the decoding if so requested
633                         // by the user.
634                         fHandler.OnError(EventHandler::kBadEndOfRegional, endOfRegional);
635                         fHadError = true;
636                         if (fExitOnError) return;
637                         
638                         // If the user requested for us to try and recover from structure
639                         // errors then we need to try locate the key in the data stream
640                         // and continue decoding from there.
641                         if (fTryRecover)
642                         {
643                                 const UChar_t* keypos = FindKey(fgkEndOfReg,
644                                                 reinterpret_cast<const UChar_t*>(regionalHeader),
645                                                 end
646                                         );
647                                 
648                                 // If the fgkEndOfReg key was found exactly one regional
649                                 // structure later then we should not adjust the current
650                                 // decoding position because it is more likely that the
651                                 // end of regional structure key was just corrupt rather
652                                 // than offset.
653                                 // If we could not find another good key then just continue.
654                                 size_t sizeOfRegional = sizeof(AliMUONRegionalHeaderStruct) + sizeof(UInt_t)
655                                         + fMaxLocals * (sizeof(AliMUONLocalInfoStruct) + sizeof(UInt_t));
656                                 if (scalarEvent)
657                                 {
658                                         sizeOfRegional += sizeof(AliMUONRegionalScalarsStruct)
659                                                 + fMaxLocals * sizeof(AliMUONLocalScalarsStruct);
660                                 }
661                                 
662                                 if (keypos != NULL and keypos != current + sizeOfRegional)
663                                 {
664                                         current = keypos + sizeof(UInt_t);
665                                 }
666                         }
667                 }
668                 
669                 // Tell the handler that we have a new regional block and decode it.
670                 // When done, tell the handler again.
671                 // We call both versions of OnNewRegionalStruct so that user event
672                 // handlers can implement the one they prefer to use.
673                 const UChar_t* startOfLocals = current;
674                 fHandler.OnNewRegionalStruct(regionalHeader, regionalScalars, startOfLocals);
675                 fHandler.OnNewRegionalStructV2(iReg, regionalHeader, regionalScalars, startOfLocals);
676                 current = DecodeLocalStructs(current, end, scalarEvent);
677                 fHandler.OnEndOfRegionalStruct(regionalHeader, regionalScalars, startOfLocals);
678                 fHandler.OnEndOfRegionalStructV2(iReg, regionalHeader, regionalScalars, startOfLocals);
679         }
680         
681         // Now just check that there is no extra rubbish at the end of the DDL.
682         if (current != end)
683         {
684                 fHandler.OnError(EventHandler::kBufferTooBig, current);
685                 fHadError = true;
686         }
687 }
688
689
690 template <class EventHandler>
691 const UChar_t* AliMUONTriggerDDLDecoder<EventHandler>::DecodeLocalStructs(
692                 const UChar_t* start, const UChar_t* end, bool scalarEvent
693         )
694 {
695         /// This method decodes the local structures in the DDL data for a
696         /// single regional structure. For each local trigger structure found,
697         /// the OnLocalStruct method of the event handler is called.
698         /// \param start  This is the pointer to the start of the regional structure
699         ///               payload (The pointer just past the regional header key).
700         /// \param end  This is the pointer to the first byte just past the
701         ///             end of the buffer.
702         /// \param scalarEvent  Set to true if this DDL contains a scalar event
703         ///     and false if it is a normal physics event.
704         /// \returns  The position in the buffer where this method stopped decoding.
705         ///
706         /// fHadError is set to true if there were any errors decoding the buffer
707         /// and the OnError method of the callback event handler is called for
708         /// each error.
709         
710         const UChar_t* current = start;
711         
712         for (UInt_t iLocal = 0; iLocal < fMaxLocals; iLocal++)
713         {
714                 const AliMUONLocalInfoStruct* localStruct =
715                         reinterpret_cast<const AliMUONLocalInfoStruct*>(current);
716                 current += sizeof(AliMUONLocalInfoStruct);
717                 
718                 if (current > end or current < start)
719                 {
720                         // If we overflowed the pointer and already had an error then
721                         // we are clearly lost so just stop decoding before we segfault.
722                         if (current < start and fHadError) return end;
723                         
724                         // So we only got part of a local structure, nothing to do but
725                         // report the error and exit.
726                         fHandler.OnError(EventHandler::kNoLocalStruct, localStruct);
727                         fHadError = true;
728                         return end;
729                 }
730                 
731                 // Skip empty local board if card not notified.
732                 if (localStruct->fX2X1 == fgkDisableWord and
733                     localStruct->fX4X3 == fgkDisableWord and
734                     localStruct->fY2Y1 == fgkDisableWord and
735                     localStruct->fY4Y3 == fgkDisableWord and
736                     localStruct->fTriggerBits == fgkDisableWord
737                    )
738                 {
739                         //current += sizeof(AliMUONLocalInfoStruct); // already done above
740                         if (scalarEvent)
741                                 current += sizeof(AliMUONLocalScalarsStruct);
742                         current += sizeof(UInt_t); // skip the end of local structure key.
743                         continue;
744                 }
745                 
746                 // Decode the regional scalar words if this is a scalar event.
747                 const AliMUONLocalScalarsStruct* localScalars = NULL;
748                 if (scalarEvent)
749                 {
750                         localScalars = reinterpret_cast<const AliMUONLocalScalarsStruct*>(current);
751                         current += sizeof(AliMUONLocalScalarsStruct);
752                         if (current > end or current < start)
753                         {
754                                 // If we overflowed the pointer and already had an error then
755                                 // we are clearly lost so just stop decoding before we segfault.
756                                 if (current < start and fHadError) return end;
757                                 
758                                 // Indicate we had an error and stop the decoding because we
759                                 // hit the end of the buffer already.
760                                 fHandler.OnError(EventHandler::kNoLocalScalars, localScalars);
761                                 fHadError = true;
762                                 return end;
763                         }
764                 }
765                 
766                 // Now check that the end of regional header marker is OK.
767                 const UInt_t* endOfLocal = reinterpret_cast<const UInt_t*>(current);
768                 current += sizeof(UInt_t);
769                 if (current > end or current < start)
770                 {
771                         // If we overflowed the pointer and already had an error then
772                         // we are clearly lost so just stop decoding before we segfault.
773                         if (current < start and fHadError) return end;
774                         
775                         // Indicate we had an error and stop the decoding because we
776                         // hit the end of the buffer already. We can however signal that
777                         // we got a local structure, because the buffer contains enough
778                         // data to potencially contain the real data of the structure.
779                         fHandler.OnError(EventHandler::kNoEndOfLocal, endOfLocal);
780                         if (not fExitOnError)
781                         {
782                                 fHandler.OnLocalStruct(localStruct, localScalars);
783                         }
784                         fHadError = true;
785                         return end;
786                 }
787                 if (*endOfLocal != fgkEndOfLocal)
788                 {
789                         // Indicate we had an error and stop the decoding if so requested
790                         // by the user.
791                         fHandler.OnError(EventHandler::kBadEndOfLocal, endOfLocal);
792                         fHadError = true;
793                         if (fExitOnError) return current;
794                         
795                         // If the user requested for us to try and recover from structure
796                         // errors then we need to try locate the key in the data stream
797                         // and continue decoding from there.
798                         if (fTryRecover)
799                         {
800                                 const UChar_t* searchPos = reinterpret_cast<const UChar_t*>(localStruct);
801                                 const UChar_t* firstLocalKey = FindKey(fgkEndOfLocal, searchPos, end);
802                                 const UChar_t* firstRegionalKey = FindKey(fgkEndOfReg, searchPos, end);
803                                 
804                                 // If a regional key was found first, then give up on
805                                 // anymore local structures from this regional block and
806                                 // continue decoding from the next regional block.
807                                 // Also if the fgkEndOfLocal key was found exactly one
808                                 // local structure later then we should not adjust the
809                                 // current decoding position because it is more likely that
810                                 // the end of local structure key was just corrupt rather
811                                 // than offset.
812                                 if (firstLocalKey != NULL and firstRegionalKey != NULL)
813                                 {
814                                         if (firstLocalKey < firstRegionalKey)
815                                         {
816                                                 size_t sizeOflocalStruct = sizeof(AliMUONLocalInfoStruct) + sizeof(UInt_t);
817                                                 if (scalarEvent)
818                                                         sizeOflocalStruct += sizeof(AliMUONLocalScalarsStruct);
819                                                 
820                                                 if (firstLocalKey != current + sizeOflocalStruct)
821                                                         current = firstLocalKey + sizeof(UInt_t);
822                                         }
823                                         else
824                                         {
825                                                 // Adjust back to the start of the regional header.
826                                                 current = firstRegionalKey - sizeof(AliMUONRegionalHeaderStruct);
827                                                 if (scalarEvent)
828                                                         current -= sizeof(AliMUONRegionalScalarsStruct);
829                                                 break;
830                                         }
831                                 }
832                                 
833                                 // If we could not find another good key then just continue.
834                         }
835                 }
836                 
837                 // Call both handlers for local structures so that the user decoder event
838                 // handler class can implement the one it prefers to use.
839                 fHandler.OnLocalStruct(localStruct, localScalars);
840                 fHandler.OnLocalStructV2(iLocal, localStruct, localScalars);
841         }
842         
843         return current;
844 }
845
846
847 template <class EventHandler>
848 const UChar_t* AliMUONTriggerDDLDecoder<EventHandler>::FindKey(
849                 UInt_t key, const UChar_t* start, const UChar_t* end
850         )
851 {
852         /// Searches for the first occurrence of the key value in the buffer
853         /// marked by 'start' and 'end'. 'start' should point to the start of
854         /// the buffer and 'end' should point to 'start + bufferSize'.
855         /// \param key  The 32 bit word to look for.
856         /// \param start  The start location to begin the search at.
857         /// \param end  The pointer to the first byte just past end of the
858         ///             buffer to check.
859         /// \returns  The location of the first occurance of key in the buffer,
860         ///           otherwise NULL is returned if nothing was found.
861  
862         if (end + sizeof(UInt_t) < start) return NULL;  // check for pointer overflow.
863         const UChar_t* current = start;
864         while (current + sizeof(UInt_t) <= end)
865         {
866                 UInt_t data = * reinterpret_cast<const UInt_t*>(current);
867                 if (data == key) return current;
868                 current++;
869         }
870         return NULL;
871 }
872
873 #endif // ALIMUONTRIGGERDDLDECODER_H