[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"
#include <ostream>

// 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,   ///< There was no reason for failure.
		kHeaderContainsWrongType,  ///< The common header contains an incorrect type ID.
		kHeaderContainsWrongRecordWidth,  ///< The common header contains an incorrect data record width.
		kReservedBitsNotZero,  ///< Reserved bits have not been set to zero.
		kParticleSignBitsNotValid,  ///< The particle sign bits are not a valid value.
		kHitNotMarkedAsNil,  ///< A hit was marked as not found, but the corresponding hit structure was not set to nil.
		kFoundDuplicateIDs,  ///< Found duplicate identifiers, but they should all be unique.
		kPtValueNotValid,  ///< The pT value is not positive nor -1 indicating an invalid value.
		kFoundDuplicateTriggers,  ///< Found duplicate trigger decisions.
		kPairTrackIdsAreIdentical,  ///< The track IDs of the track pair are identical.
		kMassValueNotValid,  ///< The invariant mass value is not positive nor -1 indicating an invalid value.
		kLowPtCountInvalid,  ///< The low pT trigger count is greater than 2, which is invalid.
		kHighPtCountInvalid  ///< The high pT trigger count is greater than 2, which is invalid.
	};
	
	/**
	 * This method converts the WhyNotValid enumeration to a string representation.
	 */
	static const char* FailureReasonToString(WhyNotValid reason);
	
	/**
	 * This method returns a string containing a user readable message explaining
	 * the reason for failure described by the WhyNotValid enumeration.
	 */
	static const char* FailureReasonToMessage(WhyNotValid reason);

	/**
	 * 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 why the header is
	 * not valid, if and only if a problem is found with the data.
	 * These methods will return either kHeaderContainsWrongType or
	 * kHeaderContainsWrongRecordWidth as the reason.
	 */
	static bool HeaderOk(const AliHLTMUONTriggerRecordsBlockStruct& block, WhyNotValid* reason = NULL);
	static bool HeaderOk(const AliHLTMUONTrigRecsDebugBlockStruct& block, WhyNotValid* reason = NULL);
	static bool HeaderOk(const AliHLTMUONTriggerChannelsBlockStruct& block, WhyNotValid* reason = NULL);
	static bool HeaderOk(const AliHLTMUONRecHitsBlockStruct& block, WhyNotValid* reason = NULL);
	static bool HeaderOk(const AliHLTMUONClustersBlockStruct& block, WhyNotValid* reason = NULL);
	static bool HeaderOk(const AliHLTMUONChannelsBlockStruct& block, WhyNotValid* reason = NULL);
	static bool HeaderOk(const AliHLTMUONMansoTracksBlockStruct& block, WhyNotValid* reason = NULL);
	static bool HeaderOk(const AliHLTMUONMansoCandidatesBlockStruct& block, WhyNotValid* reason = NULL);
	static bool HeaderOk(const AliHLTMUONSinglesDecisionBlockStruct& block, WhyNotValid* reason = NULL);
	static bool HeaderOk(const AliHLTMUONPairsDecisionBlockStruct& block, WhyNotValid* reason = NULL);

	/**
	 * 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, WhyNotValid* reason = NULL);
	
	static bool IntegrityOk(
			const AliHLTMUONTriggerRecordsBlockStruct& block,
			WhyNotValid* reason = NULL, AliHLTUInt32_t* recordNum = NULL
		);
		
	static bool IntegrityOk(const AliHLTMUONTrigRecsDebugBlockStruct& block, WhyNotValid* reason = NULL);
	static bool IntegrityOk(const AliHLTMUONTriggerChannelsBlockStruct& block, WhyNotValid* reason = NULL);
	static bool IntegrityOk(const AliHLTMUONRecHitsBlockStruct& block, WhyNotValid* reason = NULL);
	static bool IntegrityOk(const AliHLTMUONClustersBlockStruct& block, WhyNotValid* reason = NULL);
	static bool IntegrityOk(const AliHLTMUONChannelsBlockStruct& block, WhyNotValid* reason = NULL);
	static bool IntegrityOk(const AliHLTMUONMansoTrackStruct& track, WhyNotValid* reason = NULL);
	
	static bool IntegrityOk(
			const AliHLTMUONMansoTracksBlockStruct& block,
			WhyNotValid* reason = NULL, AliHLTUInt32_t* recordNum = NULL
		);
	
	static bool IntegrityOk(
			const AliHLTMUONMansoCandidatesBlockStruct& block,
			WhyNotValid* reason = NULL, AliHLTUInt32_t* recordNum = NULL
		);
	
	static bool IntegrityOk(const AliHLTMUONTrackDecisionStruct& decision, WhyNotValid* reason = NULL);
	
	static bool IntegrityOk(
			const AliHLTMUONSinglesDecisionBlockStruct& block,
			WhyNotValid* reason = NULL, AliHLTUInt32_t* recordNum = NULL
		);
	
	static bool IntegrityOk(const AliHLTMUONPairDecisionStruct& decision, WhyNotValid* reason = NULL);
	
	static bool IntegrityOk(
			const AliHLTMUONPairsDecisionBlockStruct& block,
			WhyNotValid* reason = NULL, AliHLTUInt32_t* recordNum = NULL
		);

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

//_____________________________________________________________________________

inline std::ostream& operator << (std::ostream& stream, AliHLTMUONUtils::WhyNotValid reason)
{
	/// Stream operator for the WhyNotValid enumeration for usage with
	/// std::ostream classes. Allows usages such as:
	/// AliHLTMUONUtils::WhyNotValid r; std::cout << r;
	
	stream << AliHLTMUONUtils::FailureReasonToString(reason);
	return stream;
}

//_____________________________________________________________________________

// 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__

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