[u/mrichter/AliRoot.git] / HLT / MUON / AliHLTMUONUtils.h

#ifndef ALIHLTMUONUTILS_H
#define ALIHLTMUONUTILS_H
/* Copyright(c) 1998-2007, ALICE Experiment at CERN, All rights reserved. *
 * See cxx source for full Copyright notice                               */

/* $Id$ */

///
/// @file   AliHLTMUONUtils.h
/// @author Artur Szostak <artursz@iafrica.com>
/// @date   
/// @brief  Class containing various dimuon HLT utility routines and macros.
///

#include "AliHLTMUONDataTypes.h"

// Forward declare structures.
extern "C" {
struct AliHLTMUONTriggerRecordStruct;
struct AliHLTMUONTriggerRecordsBlockStruct;
struct AliHLTMUONTrigRecsDebugBlockStruct;
struct AliHLTMUONTriggerChannelsBlockStruct;
struct AliHLTMUONRecHitsBlockStruct;
struct AliHLTMUONClustersBlockStruct;
struct AliHLTMUONChannelsBlockStruct;
struct AliHLTMUONMansoTrackStruct;
struct AliHLTMUONMansoTracksBlockStruct;
struct AliHLTMUONMansoCandidatesBlockStruct;
struct AliHLTMUONTrackDecisionStruct;
struct AliHLTMUONSinglesDecisionBlockStruct;
struct AliHLTMUONPairDecisionStruct;
struct AliHLTMUONPairsDecisionBlockStruct;
} // extern "C"

/**
 * AliHLTMUONUtils contains arbitrary utility methods to be used in various
 * parts of the dimuon HLT system.
 * These include methods to perform basic sanity checks on the integrity of
 * data blocks.
 */
class AliHLTMUONUtils
{
public:
	/**
	 * This packs the given parameters into the bits of a word appropriate
	 * for AliHLTMUONTriggerRecordStruct::fFlags.
	 * @param sign    The particle sign.
	 * @param hitset  Flags to indicate if the corresponding fHits[i] elements
	 *                was set/filled.
	 * @return  Returns the 32 bit packed word.
	 */
	static AliHLTUInt32_t PackTriggerRecordFlags(
			AliHLTMUONParticleSign sign, const bool hitset[4]
		);

	/**
	 * This unpacks the AliHLTMUONTriggerRecordStruct::fFlags bits into
	 * its component fields.
	 * @param flags  The flags from an AliHLTMUONTriggerRecordStruct structure.
	 * @param sign    Sets this to the particle sign.
	 * @param hitset  Sets the array elements to indicate if the corresponding
	 *                fHits[i] element was set/filled.
	 */
	static void UnpackTriggerRecordFlags(
			AliHLTUInt32_t flags, // [in]
			AliHLTMUONParticleSign& sign, // [out]
			bool hitset[4] // [out]
		);

	/**
	 * This packs the given parameters into the bits of a word appropriate
	 * for AliHLTMUONMansoTrackStruct::fFlags.
	 * @param sign    The particle sign.
	 * @param hitset  Flags to indicate if the corresponding fHits[i] elements
	 *                was set/filled.
	 * @return  Returns the 32 bit packed word.
	 */
	static AliHLTUInt32_t PackMansoTrackFlags(
			AliHLTMUONParticleSign sign, const bool hitset[4]
		)
	{
		return PackTriggerRecordFlags(sign, hitset);
	}

	/**
	 * This unpacks the AliHLTMUONMansoTrackStruct::fFlags bits into
	 * its component fields.
	 * @param flags  The flags from an AliHLTMUONMansoTrackStruct structure.
	 * @param sign    Sets this to the particle sign.
	 * @param hitset  Sets the array elements to indicate if the corresponding
	 *                fHits[i] element was set/filled.
	 */
	static void UnpackMansoTrackFlags(
			AliHLTUInt32_t flags, // [in]
			AliHLTMUONParticleSign& sign, // [out]
			bool hitset[4] // [out]
		)
	{
		UnpackTriggerRecordFlags(flags, sign, hitset);
	}
	
	/**
	 * This packs the given parameters into the bits of a word appropriate
	 * for AliHLTMUONTrackDecisionStruct::fTriggerBits.
	 * @param highPt  Has the track passed the high pt cut.
	 * @param lowPt   Has the track passed the low pt cut.
	 * @return  Returns the 32 bit packed word.
	 */
	static AliHLTUInt32_t PackTrackDecisionBits(bool highPt, bool lowPt);
	
	/**
	 * This unpacks the AliHLTMUONTrackDecisionStruct::fTriggerBits bits into
	 * its component fields.
	 * @param bits  The trigger bits from an AliHLTMUONTrackDecisionStruct
	 *              structure.
	 * @param highPt Sets this to the value of the high pt cut bit.
	 * @param lowPt  Sets this to the value of the low pt cut bit.
	 */
	static void UnpackTrackDecisionBits(
			AliHLTUInt32_t bits, // [in]
			bool& highPt, // [out]
			bool& lowPt // [out]
		);
	
	/**
	 * This packs the given parameters into the bits of a word appropriate
	 * for AliHLTMUONPairDecisionStruct::fTriggerBits.
	 *
	 * @param highMass Has the track pair passed the high invariant mass cut.
	 * @param lowMass  Has the track pair passed the low invariant mass cut.
	 * @param unlike   Does the track pair have unlike signs.
	 * @param highPtCount The number of tracks that passed the high pt cut
	 *                    in the pair.
	 * @param lowPtCount  The number of tracks that passed the low pt cut
	 *                    in the pair.
	 * @return  Returns the 32 bit packed word.
	 *
	 * Note: Must have highPtCount + lowPtCount <= 2 and unlike == true if
	 * highMass or lowMass is true.
	 */
	static AliHLTUInt32_t PackPairDecisionBits(
			bool highMass, bool lowMass, bool unlike,
			AliHLTUInt8_t highPtCount, AliHLTUInt8_t lowPtCount
		);
	
	/**
	 * This unpacks the AliHLTMUONPairDecisionStruct::fTriggerBits bits into
	 * its component fields.
	 * @param bits  The trigger bits from an AliHLTMUONPairDecisionStruct
	 *              structure.
	 * @param highMass Sets this to the value of the high invariant mass cut bit.
	 * @param lowMass  Sets this to the value of the low invariant mass cut bit.
	 * @param unlike   Sets this if the pair is unlike sign.
	 * @param highPtCount Sets this to the high pt count bits.
	 * @param lowPtCount  Sets this to the low pt count bits.
	 */
	static void UnpackPairDecisionBits(
			AliHLTUInt32_t bits, // [in]
			bool& highMass, // [out]
			bool& lowMass, // [out]
			bool& unlike, // [out]
			AliHLTUInt8_t& highPtCount, // [out]
			AliHLTUInt8_t& lowPtCount // [out]
		);
	
	/**
	 * This packs the given parameters into the 32bit Pub/Sub specification
	 * word in the data block descriptor.
	 *
	 * @param ddl  The list of DDLs forming part of the readout. ddl[0]
	 *             indicates DDL number 2560, ddl[1] is for DDL 2561 and so
	 *             on up to ddl[19]. ddl[20] and ddl[21] will be for the
	 *             trigger DDLs 2816 and 2817 respectively.
	 * @return  Returns the 32 bit packed specification word.
	 */
	static AliHLTUInt32_t PackSpecBits(
			const bool ddl[22]
		);
	
	/**
	 * This unpacks the AliHLTMUONPairDecisionStruct::fTriggerBits bits into
	 * its component fields.
	 * @param bits  The Pub/Sub specification word from a data block descriptor.
	 * @param ddl  The output list of DDLs forming part of the readout. ddl[0]
	 *             indicates DDL number 2560, ddl[1] is for DDL 2561 and so
	 *             on up to ddl[19]. ddl[20] and ddl[21] will be for the
	 *             trigger DDLs 2816 and 2817 respectively.
	 */
	static void UnpackSpecBits(
			AliHLTUInt32_t bits, // [in]
			bool ddl[22] // [out]
		);

	/**
	 * This method converts the DDL number for the muon spectrometer in the
	 * range [0..21] to the equipment ID number.
	 * @param ddlNo  The DDL number in the range [0..21].
	 * @return  Returns the equipment ID number or -1 if ddlNo was invalid.
	 */
	static AliHLTInt32_t DDLNumberToEquipId(AliHLTInt32_t ddlNo);
	
	/**
	 * This method converts the equipment ID number for a muon spectrometer
	 * DDL to the DDL number in the range [0..21].
	 * @param id  The equipment ID of the DDL.
	 * @return  Returns the DDL number in the range [0..21] or -1 if the
	 *          equipment ID was invalid.
	 */
	static AliHLTInt32_t EquipIdToDDLNumber(AliHLTInt32_t id);
	
	/**
	 * This method converts a 32 bit data block specification for a MUON-HLT
	 * data block into its corresponding DDL equipment ID number.
	 * It is assumed that the specification is for a data block comming from
	 * a single DDL source. If more than one DDL contributed to the data block
	 * then -1 is returned.
	 * @param spec  The 32 bit specification for a data block.
	 * @return  Returns the equipment ID corresponding to the specification
	 *          or -1 if the specification was invalid.
	 */
	static AliHLTInt32_t SpecToEquipId(AliHLTUInt32_t spec);
	
	/**
	 * This method converts a equipment ID number for a DDL into its corresponding
	 * 32 bit data block specification for the MUON-HLT.
	 * @param id  The equipment ID number of the DDL.
	 * @return  Returns the 32 bit data block specification or 0x0 if the
	 *          equipment ID was invalid.
	 */
	static AliHLTUInt32_t EquipIdToSpec(AliHLTInt32_t id);
	
	/**
	 * This method converts a 32 bit data block specification for a MUON-HLT
	 * data block into its corresponding DDL number in the range [0..21].
	 * It is assumed that the specification is for a data block comming from
	 * a single DDL source. If more than one DDL contributed to the data block
	 * then -1 is returned.
	 * @param spec  The 32 bit specification for a data block.
	 * @return  Returns the corresponding DDL number for the specification
	 *          or -1 if the specification was invalid.
	 */
	static AliHLTInt32_t SpecToDDLNumber(AliHLTUInt32_t spec);
	
	/**
	 * This method converts a DDL number in the range [0..21] into its
	 * corresponding 32 bit data block specification for the MUON-HLT.
	 * @param ddlNo  The equipment ID number of the DDL.
	 * @return  Returns the 32 bit data block specification or 0x0 if the
	 *          DDL number was invalid (out of range).
	 */
	static AliHLTUInt32_t DDLNumberToSpec(AliHLTInt32_t ddlNo);

	/**
	 * Returns true if the given specification was for a single trigger DDL.
	 */
	static bool IsTriggerDDL(AliHLTUInt32_t spec)
	{
		AliHLTInt32_t ddl = SpecToDDLNumber(spec);
		return (20 <= ddl and ddl <= 21);
	}

	/**
	 * Returns true if the given specification was for a single tracker DDL.
	 */
	static bool IsTrackerDDL(AliHLTUInt32_t spec)
	{
		AliHLTInt32_t ddl = SpecToDDLNumber(spec);
		return (0 <= ddl and ddl <= 19);
	}
	
	/**
	* Parses the string containing the type name of a dHLT data block and
	* returns the corresponding AliHLTMUONDataBlockType value.
	* \param  type  The string containing the type name.
	* \returns  The data block type or kUnknownDataBlock if the type name
	*      is invalid.
	*/
	static AliHLTMUONDataBlockType ParseCommandLineTypeString(const char* type);

	/**
	 * These codes indicate the reason why a data block failed its
	 * validity check.
	 */
	enum WhyNotValid
	{
		kNoReason,
		kHeaderContainsWrongType,
		kHeaderContainsWrongRecordWidth
	};

	/**
	 * Methods used to check if the header information corresponds to the
	 * supposed type of the data block.
	 * If the 'reason' parameter is not NULL then these methods will fill the
	 * memory pointed to by reason with a code describing of why the header
	 * is not valid, if and only if a problem is found with the data.
	 */
	static bool HeaderOk(const AliHLTMUONTriggerRecordsBlockStruct& block, WhyNotValid* reason = NULL);
	static bool HeaderOk(const AliHLTMUONTrigRecsDebugBlockStruct& block);
	static bool HeaderOk(const AliHLTMUONTriggerChannelsBlockStruct& block);
	static bool HeaderOk(const AliHLTMUONRecHitsBlockStruct& block);
	static bool HeaderOk(const AliHLTMUONClustersBlockStruct& block);
	static bool HeaderOk(const AliHLTMUONChannelsBlockStruct& block);
	static bool HeaderOk(const AliHLTMUONMansoTracksBlockStruct& block);
	static bool HeaderOk(const AliHLTMUONMansoCandidatesBlockStruct& block);
	static bool HeaderOk(const AliHLTMUONSinglesDecisionBlockStruct& block);
	static bool HeaderOk(const AliHLTMUONPairsDecisionBlockStruct& block);

	/**
	 * Methods used to check more extensively if the integrity of various
	 * types of data blocks are Ok and returns true in that case.
	 * These can be slow and should generally only be used for debugging.
	 */
	static bool IntegrityOk(const AliHLTMUONTriggerRecordStruct& tr);
	static bool IntegrityOk(const AliHLTMUONTriggerRecordsBlockStruct& block);
	static bool IntegrityOk(const AliHLTMUONTrigRecsDebugBlockStruct& block);
	static bool IntegrityOk(const AliHLTMUONTriggerChannelsBlockStruct& block);
	static bool IntegrityOk(const AliHLTMUONRecHitsBlockStruct& block);
	static bool IntegrityOk(const AliHLTMUONClustersBlockStruct& block);
	static bool IntegrityOk(const AliHLTMUONChannelsBlockStruct& block);
	static bool IntegrityOk(const AliHLTMUONMansoTrackStruct& track);
	static bool IntegrityOk(const AliHLTMUONMansoTracksBlockStruct& block);
	static bool IntegrityOk(const AliHLTMUONMansoCandidatesBlockStruct& block);
	static bool IntegrityOk(const AliHLTMUONTrackDecisionStruct& decision);
	static bool IntegrityOk(const AliHLTMUONSinglesDecisionBlockStruct& block);
	static bool IntegrityOk(const AliHLTMUONPairDecisionStruct& decision);
	static bool IntegrityOk(const AliHLTMUONPairsDecisionBlockStruct& block);

private:
	// Should never have to create or destroy this object.
	AliHLTMUONUtils();
	~AliHLTMUONUtils();
};

//_____________________________________________________________________________

// Since c++ is missing a finally "keyword" we define one. Its usage is identical
// to a try..finally statement in Java etc.. however, since it is officialy a macro
// one must use the ( ) brackets instead of { }
// If the compiler supports __finally use it otherwise make our own.
#if defined(__BORLANDC__)
#	define finally(str) __finally{str}
#else
#	define finally(code) \
		catch(...) \
		{ \
			code \
			throw; \
		}; \
		code
#endif // __BORLANDC__

// If we do not already have them, then define logical operators that are easier
// to read. 'and' = &&, 'or' = ||, 'not' = !
#if ! defined(__GNUC__) && ! defined(__CINT__)
// TODO: Should use iso646.h
#	define and &&
#	define or ||
#	define not !
#endif // __GNUC__ | __CINT__


// Here we define the DebugTrace(message) macro for easy embedding of debug
// information into the dimuon HLT code. Its usage is meant to be for generating
// traces of the program which are only useful during full scale debugging.
// Log messages should use the standard HLT logging mechanisms.
// The output is only generated in programs compiled with the DEBUG directive
// defined. Here is a usage example:
//
//  // statements...
//  DebugTrace("some debug information.");
//  // statements...
//
// One can also use C++ ostream operators and manipulators like so:
//
//  // statements...
//  int x, y;
//  DebugTrace("x = " << x << " and y = 0x" << std::hex << y );
//  // statements...
//
#ifdef DEBUG
#	include <iostream>
#	define DebugTrace(message) {std::cout << message << std::endl;}
#else // DEBUG
#	define DebugTrace(message)
#endif // DEBUG


#endif // ALIHLTMUONUTILS_H
Commit	Line	Data
26a4668d	1	#ifndef ALIHLTMUONUTILS_H
	2	#define ALIHLTMUONUTILS_H
	3	/* Copyright(c) 1998-2007, ALICE Experiment at CERN, All rights reserved. *
	4	* See cxx source for full Copyright notice */
	5
	6	/* $Id$ */
	7
6253e09b	8	///
	9	/// @file AliHLTMUONUtils.h
	10	/// @author Artur Szostak <artursz@iafrica.com>
	11	/// @date
	12	/// @brief Class containing various dimuon HLT utility routines and macros.
	13	///
26a4668d	14
c8ec7c7e	15	#include "AliHLTMUONDataTypes.h"
	16
	17	// Forward declare structures.
	18	extern "C" {
90a74d7a	19	struct AliHLTMUONTriggerRecordStruct;
c8ec7c7e	20	struct AliHLTMUONTriggerRecordsBlockStruct;
	21	struct AliHLTMUONTrigRecsDebugBlockStruct;
	22	struct AliHLTMUONTriggerChannelsBlockStruct;
	23	struct AliHLTMUONRecHitsBlockStruct;
	24	struct AliHLTMUONClustersBlockStruct;
	25	struct AliHLTMUONChannelsBlockStruct;
90a74d7a	26	struct AliHLTMUONMansoTrackStruct;
	27	struct AliHLTMUONMansoTracksBlockStruct;
	28	struct AliHLTMUONMansoCandidatesBlockStruct;
	29	struct AliHLTMUONTrackDecisionStruct;
	30	struct AliHLTMUONSinglesDecisionBlockStruct;
	31	struct AliHLTMUONPairDecisionStruct;
	32	struct AliHLTMUONPairsDecisionBlockStruct;
c8ec7c7e	33	} // extern "C"
26a4668d	34
	35	/**
	36	* AliHLTMUONUtils contains arbitrary utility methods to be used in various
	37	* parts of the dimuon HLT system.
	38	* These include methods to perform basic sanity checks on the integrity of
	39	* data blocks.
	40	*/
	41	class AliHLTMUONUtils
	42	{
	43	public:
b727f838	44	/**
	45	* This packs the given parameters into the bits of a word appropriate
	46	* for AliHLTMUONTriggerRecordStruct::fFlags.
	47	* @param sign The particle sign.
	48	* @param hitset Flags to indicate if the corresponding fHits[i] elements
	49	* was set/filled.
	50	* @return Returns the 32 bit packed word.
	51	*/
	52	static AliHLTUInt32_t PackTriggerRecordFlags(
e6357f88	53	AliHLTMUONParticleSign sign, const bool hitset[4]
b727f838	54	);
	55
	56	/**
	57	* This unpacks the AliHLTMUONTriggerRecordStruct::fFlags bits into
	58	* its component fields.
	59	* @param flags The flags from an AliHLTMUONTriggerRecordStruct structure.
	60	* @param sign Sets this to the particle sign.
	61	* @param hitset Sets the array elements to indicate if the corresponding
	62	* fHits[i] element was set/filled.
	63	*/
	64	static void UnpackTriggerRecordFlags(
	65	AliHLTUInt32_t flags, // [in]
	66	AliHLTMUONParticleSign& sign, // [out]
	67	bool hitset[4] // [out]
	68	);
	69
	70	/**
	71	* This packs the given parameters into the bits of a word appropriate
	72	* for AliHLTMUONMansoTrackStruct::fFlags.
	73	* @param sign The particle sign.
	74	* @param hitset Flags to indicate if the corresponding fHits[i] elements
	75	* was set/filled.
	76	* @return Returns the 32 bit packed word.
	77	*/
	78	static AliHLTUInt32_t PackMansoTrackFlags(
e6357f88	79	AliHLTMUONParticleSign sign, const bool hitset[4]
b727f838	80	)
	81	{
	82	return PackTriggerRecordFlags(sign, hitset);
	83	}
	84
	85	/**
	86	* This unpacks the AliHLTMUONMansoTrackStruct::fFlags bits into
	87	* its component fields.
	88	* @param flags The flags from an AliHLTMUONMansoTrackStruct structure.
	89	* @param sign Sets this to the particle sign.
	90	* @param hitset Sets the array elements to indicate if the corresponding
	91	* fHits[i] element was set/filled.
	92	*/
	93	static void UnpackMansoTrackFlags(
	94	AliHLTUInt32_t flags, // [in]
	95	AliHLTMUONParticleSign& sign, // [out]
	96	bool hitset[4] // [out]
	97	)
	98	{
	99	UnpackTriggerRecordFlags(flags, sign, hitset);
	100	}
90a74d7a	101
	102	/**
	103	* This packs the given parameters into the bits of a word appropriate
	104	* for AliHLTMUONTrackDecisionStruct::fTriggerBits.
	105	* @param highPt Has the track passed the high pt cut.
	106	* @param lowPt Has the track passed the low pt cut.
	107	* @return Returns the 32 bit packed word.
	108	*/
	109	static AliHLTUInt32_t PackTrackDecisionBits(bool highPt, bool lowPt);
	110
	111	/**
	112	* This unpacks the AliHLTMUONTrackDecisionStruct::fTriggerBits bits into
	113	* its component fields.
	114	* @param bits The trigger bits from an AliHLTMUONTrackDecisionStruct
	115	* structure.
	116	* @param highPt Sets this to the value of the high pt cut bit.
	117	* @param lowPt Sets this to the value of the low pt cut bit.
	118	*/
	119	static void UnpackTrackDecisionBits(
	120	AliHLTUInt32_t bits, // [in]
	121	bool& highPt, // [out]
	122	bool& lowPt // [out]
	123	);
	124
	125	/**
	126	* This packs the given parameters into the bits of a word appropriate
	127	* for AliHLTMUONPairDecisionStruct::fTriggerBits.
	128	*
	129	* @param highMass Has the track pair passed the high invariant mass cut.
	130	* @param lowMass Has the track pair passed the low invariant mass cut.
	131	* @param unlike Does the track pair have unlike signs.
	132	* @param highPtCount The number of tracks that passed the high pt cut
	133	* in the pair.
	134	* @param lowPtCount The number of tracks that passed the low pt cut
	135	* in the pair.
	136	* @return Returns the 32 bit packed word.
	137	*
	138	* Note: Must have highPtCount + lowPtCount <= 2 and unlike == true if
	139	* highMass or lowMass is true.
	140	*/
	141	static AliHLTUInt32_t PackPairDecisionBits(
	142	bool highMass, bool lowMass, bool unlike,
	143	AliHLTUInt8_t highPtCount, AliHLTUInt8_t lowPtCount
	144	);
	145
	146	/**
	147	* This unpacks the AliHLTMUONPairDecisionStruct::fTriggerBits bits into
	148	* its component fields.
	149	* @param bits The trigger bits from an AliHLTMUONPairDecisionStruct
	150	* structure.
	151	* @param highMass Sets this to the value of the high invariant mass cut bit.
	152	* @param lowMass Sets this to the value of the low invariant mass cut bit.
	153	* @param unlike Sets this if the pair is unlike sign.
	154	* @param highPtCount Sets this to the high pt count bits.
	155	* @param lowPtCount Sets this to the low pt count bits.
	156	*/
	157	static void UnpackPairDecisionBits(
	158	AliHLTUInt32_t bits, // [in]
	159	bool& highMass, // [out]
	160	bool& lowMass, // [out]
	161	bool& unlike, // [out]
	162	AliHLTUInt8_t& highPtCount, // [out]
	163	AliHLTUInt8_t& lowPtCount // [out]
	164	);
e6357f88	165
	166	/**
	167	* This packs the given parameters into the 32bit Pub/Sub specification
	168	* word in the data block descriptor.
	169	*
	170	* @param ddl The list of DDLs forming part of the readout. ddl[0]
	171	* indicates DDL number 2560, ddl[1] is for DDL 2561 and so
	172	* on up to ddl[19]. ddl[20] and ddl[21] will be for the
	173	* trigger DDLs 2816 and 2817 respectively.
	174	* @return Returns the 32 bit packed specification word.
	175	*/
	176	static AliHLTUInt32_t PackSpecBits(
	177	const bool ddl[22]
	178	);
	179
	180	/**
	181	* This unpacks the AliHLTMUONPairDecisionStruct::fTriggerBits bits into
	182	* its component fields.
	183	* @param bits The Pub/Sub specification word from a data block descriptor.
	184	* @param ddl The output list of DDLs forming part of the readout. ddl[0]
	185	* indicates DDL number 2560, ddl[1] is for DDL 2561 and so
	186	* on up to ddl[19]. ddl[20] and ddl[21] will be for the
	187	* trigger DDLs 2816 and 2817 respectively.
	188	*/
	189	static void UnpackSpecBits(
	190	AliHLTUInt32_t bits, // [in]
	191	bool ddl[22] // [out]
	192	);
26a4668d	193
86b774d9	194	/**
	195	* This method converts the DDL number for the muon spectrometer in the
	196	* range [0..21] to the equipment ID number.
	197	* @param ddlNo The DDL number in the range [0..21].
	198	* @return Returns the equipment ID number or -1 if ddlNo was invalid.
	199	*/
	200	static AliHLTInt32_t DDLNumberToEquipId(AliHLTInt32_t ddlNo);
	201
	202	/**
	203	* This method converts the equipment ID number for a muon spectrometer
	204	* DDL to the DDL number in the range [0..21].
	205	* @param id The equipment ID of the DDL.
	206	* @return Returns the DDL number in the range [0..21] or -1 if the
	207	* equipment ID was invalid.
	208	*/
	209	static AliHLTInt32_t EquipIdToDDLNumber(AliHLTInt32_t id);
	210
	211	/**
	212	* This method converts a 32 bit data block specification for a MUON-HLT
	213	* data block into its corresponding DDL equipment ID number.
	214	* It is assumed that the specification is for a data block comming from
	215	* a single DDL source. If more than one DDL contributed to the data block
	216	* then -1 is returned.
	217	* @param spec The 32 bit specification for a data block.
	218	* @return Returns the equipment ID corresponding to the specification
	219	* or -1 if the specification was invalid.
	220	*/
	221	static AliHLTInt32_t SpecToEquipId(AliHLTUInt32_t spec);
	222
	223	/**
	224	* This method converts a equipment ID number for a DDL into its corresponding
	225	* 32 bit data block specification for the MUON-HLT.
	226	* @param id The equipment ID number of the DDL.
	227	* @return Returns the 32 bit data block specification or 0x0 if the
	228	* equipment ID was invalid.
	229	*/
	230	static AliHLTUInt32_t EquipIdToSpec(AliHLTInt32_t id);
	231
	232	/**
	233	* This method converts a 32 bit data block specification for a MUON-HLT
	234	* data block into its corresponding DDL number in the range [0..21].
	235	* It is assumed that the specification is for a data block comming from
	236	* a single DDL source. If more than one DDL contributed to the data block
	237	* then -1 is returned.
	238	* @param spec The 32 bit specification for a data block.
	239	* @return Returns the corresponding DDL number for the specification
	240	* or -1 if the specification was invalid.
	241	*/
	242	static AliHLTInt32_t SpecToDDLNumber(AliHLTUInt32_t spec);
	243
	244	/**
	245	* This method converts a DDL number in the range [0..21] into its
	246	* corresponding 32 bit data block specification for the MUON-HLT.
	247	* @param ddlNo The equipment ID number of the DDL.
	248	* @return Returns the 32 bit data block specification or 0x0 if the
	249	* DDL number was invalid (out of range).
	250	*/
	251	static AliHLTUInt32_t DDLNumberToSpec(AliHLTInt32_t ddlNo);
	252
668eee9f	253	/**
	254	* Returns true if the given specification was for a single trigger DDL.
	255	*/
	256	static bool IsTriggerDDL(AliHLTUInt32_t spec)
	257	{
	258	AliHLTInt32_t ddl = SpecToDDLNumber(spec);
	259	return (20 <= ddl and ddl <= 21);
	260	}
	261
	262	/**
	263	* Returns true if the given specification was for a single tracker DDL.
	264	*/
	265	static bool IsTrackerDDL(AliHLTUInt32_t spec)
	266	{
	267	AliHLTInt32_t ddl = SpecToDDLNumber(spec);
	268	return (0 <= ddl and ddl <= 19);
	269	}
f68b4e0e	270
	271	/**
	272	* Parses the string containing the type name of a dHLT data block and
	273	* returns the corresponding AliHLTMUONDataBlockType value.
	274	* \param type The string containing the type name.
	275	* \returns The data block type or kUnknownDataBlock if the type name
	276	* is invalid.
	277	*/
	278	static AliHLTMUONDataBlockType ParseCommandLineTypeString(const char* type);
668eee9f	279
698c9498	280	/**
	281	* These codes indicate the reason why a data block failed its
	282	* validity check.
	283	*/
	284	enum WhyNotValid
	285	{
	286	kNoReason,
	287	kHeaderContainsWrongType,
9c234d7b	288	kHeaderContainsWrongRecordWidth
698c9498	289	};
698c9498	290
26a4668d	291	/**
b727f838	292	* Methods used to check if the header information corresponds to the
b727f838	293	* supposed type of the data block.
698c9498	294	* If the 'reason' parameter is not NULL then these methods will fill the
	295	* memory pointed to by reason with a code describing of why the header
	296	* is not valid, if and only if a problem is found with the data.
26a4668d	297	*/
698c9498	298	static bool HeaderOk(const AliHLTMUONTriggerRecordsBlockStruct& block, WhyNotValid* reason = NULL);
c8ec7c7e	299	static bool HeaderOk(const AliHLTMUONTrigRecsDebugBlockStruct& block);
c8ec7c7e	300	static bool HeaderOk(const AliHLTMUONTriggerChannelsBlockStruct& block);
b727f838	301	static bool HeaderOk(const AliHLTMUONRecHitsBlockStruct& block);
	302	static bool HeaderOk(const AliHLTMUONClustersBlockStruct& block);
	303	static bool HeaderOk(const AliHLTMUONChannelsBlockStruct& block);
90a74d7a	304	static bool HeaderOk(const AliHLTMUONMansoTracksBlockStruct& block);
	305	static bool HeaderOk(const AliHLTMUONMansoCandidatesBlockStruct& block);
	306	static bool HeaderOk(const AliHLTMUONSinglesDecisionBlockStruct& block);
	307	static bool HeaderOk(const AliHLTMUONPairsDecisionBlockStruct& block);
b727f838	308
b727f838	309	/**
90a74d7a	310	* Methods used to check more extensively if the integrity of various
90a74d7a	311	* types of data blocks are Ok and returns true in that case.
b727f838	312	* These can be slow and should generally only be used for debugging.
b727f838	313	*/
90a74d7a	314	static bool IntegrityOk(const AliHLTMUONTriggerRecordStruct& tr);
b727f838	315	static bool IntegrityOk(const AliHLTMUONTriggerRecordsBlockStruct& block);
c8ec7c7e	316	static bool IntegrityOk(const AliHLTMUONTrigRecsDebugBlockStruct& block);
c8ec7c7e	317	static bool IntegrityOk(const AliHLTMUONTriggerChannelsBlockStruct& block);
b727f838	318	static bool IntegrityOk(const AliHLTMUONRecHitsBlockStruct& block);
	319	static bool IntegrityOk(const AliHLTMUONClustersBlockStruct& block);
	320	static bool IntegrityOk(const AliHLTMUONChannelsBlockStruct& block);
90a74d7a	321	static bool IntegrityOk(const AliHLTMUONMansoTrackStruct& track);
	322	static bool IntegrityOk(const AliHLTMUONMansoTracksBlockStruct& block);
	323	static bool IntegrityOk(const AliHLTMUONMansoCandidatesBlockStruct& block);
	324	static bool IntegrityOk(const AliHLTMUONTrackDecisionStruct& decision);
	325	static bool IntegrityOk(const AliHLTMUONSinglesDecisionBlockStruct& block);
	326	static bool IntegrityOk(const AliHLTMUONPairDecisionStruct& decision);
	327	static bool IntegrityOk(const AliHLTMUONPairsDecisionBlockStruct& block);
26a4668d	328
	329	private:
	330	// Should never have to create or destroy this object.
	331	AliHLTMUONUtils();
	332	~AliHLTMUONUtils();
	333	};
	334
b727f838	335	//_____________________________________________________________________________
	336
	337	// Since c++ is missing a finally "keyword" we define one. Its usage is identical
	338	// to a try..finally statement in Java etc.. however, since it is officialy a macro
	339	// one must use the ( ) brackets instead of { }
	340	// If the compiler supports __finally use it otherwise make our own.
	341	#if defined(__BORLANDC__)
	342	# define finally(str) __finally{str}
	343	#else
	344	# define finally(code) \
	345	catch(...) \
	346	{ \
	347	code \
	348	throw; \
	349	}; \
	350	code
	351	#endif // __BORLANDC__
	352
	353	// If we do not already have them, then define logical operators that are easier
	354	// to read. 'and' = &&, 'or' = \|\|, 'not' = !
	355	#if ! defined(__GNUC__) && ! defined(__CINT__)
b12fe461	356	// TODO: Should use iso646.h
b727f838	357	# define and &&
	358	# define or \|\|
	359	# define not !
	360	#endif // __GNUC__ \| __CINT__
	361
	362
	363	// Here we define the DebugTrace(message) macro for easy embedding of debug
	364	// information into the dimuon HLT code. Its usage is meant to be for generating
	365	// traces of the program which are only useful during full scale debugging.
	366	// Log messages should use the standard HLT logging mechanisms.
	367	// The output is only generated in programs compiled with the DEBUG directive
	368	// defined. Here is a usage example:
	369	//
	370	// // statements...
	371	// DebugTrace("some debug information.");
	372	// // statements...
	373	//
	374	// One can also use C++ ostream operators and manipulators like so:
	375	//
	376	// // statements...
	377	// int x, y;
b12fe461	378	// DebugTrace("x = " << x << " and y = 0x" << std::hex << y );
b727f838	379	// // statements...
	380	//
	381	#ifdef DEBUG
b4dfa1c8	382	# include <iostream>
b727f838	383	# define DebugTrace(message) {std::cout << message << std::endl;}
	384	#else // DEBUG
	385	# define DebugTrace(message)
	386	#endif // DEBUG
	387
	388
26a4668d	389	#endif // ALIHLTMUONUTILS_H