---

CAENcard Class Reference

Drivers for the CAEN V775 TDC, V785 ADC, and V792 QDC modules. More...

#include <CAENcard.h>

List of all members.

Public Methods
	CAENcard (int slotNum=0, int crateNum=0)
	Standard constructor. SlotNum is required to create a valid card, crateNum is not. More...
	CAENcard (const CAENcard &card)
	Another constructor. Allows a card to be created using another card. More...
CAENcard &	operator= (const CAENcard &card)
	The card being assigned to has the destructor called on it and the value of the other argument assigned to it. More...
	~CAENcard ()
	Reference counted destructor. The cards are not de-allocated until there are no references to them. More...
int	cardType ()
	Returns the module number of the card in the slot. More...
void	setCrate (int crateNum)
	Sets the crate value that appears in the header of each data event. More...
int	getCrate ()
	Returns an integer containing the current crate value. More...
void	setThreshold (int ch, int threshold)
	Changes the raw 12-bit threshold value on any card. More...
int	setThresholdVoltage (int ch, double voltage)
	Sets the threshold on the 785 ADC based upon the specified voltage value. More...
void	keepUnderThresholdData ()
	Allows conversions that resulted in under threshold values to be retained. More...
void	discardUnderThresholdData ()
	Instructs the module to discard all under threshold conversions. (default). More...
void	keepOverflowData ()
	Allows conversions that resulted in an overflow to be kept. More...
void	discardOverflowData ()
	Instructs the module to discard all conversions that overflow. (default). More...
int	keepInvalidData ()
	Allows conversions that take place while the TDC is reseting to be kept. More...
int	discardInvalidData ()
	Instructs the module to discard all conversions performed while the TDC is reseting. (default). More...
int	commonStart ()
	Sets the TDC to run in common start mode. More...
int	commonStop ()
	Sets the TDC to run in common stop mode. More...
int	setRange (int range)
	Sets the range on a TDC (from 140 to 1200 ns). More...
int	setPedestalCurrent (int ped)
	Sets the pedestal current and resolution on a QDC. More...
void	cardOff ()
	Prevents the card from performing convertions until cardOn() or reset() is called. More...
void	cardOn ()
	Puts the card into online mode. (default) This function is not needed unless cardOff() has been previously called. More...
void	channelOff (int ch)
	Prevents the module from saving any conversions for the specified channel in the event buffer. More...
void	channelOn (int ch)
	Makes sure that the module can save conversions for the specified channel. More...
void	resetEventCounter ()
	Resets the value in the event counter to zero. More...
void	clearData ()
	Clears all data from the event buffer and usually the event counter, too (if not in "count all triggers" mode). More...
void	reset ()
	Clears all data from the buffer and clears most settings (they are set to default values by the card)v. More...
int	dataPresent ()
	A simple test to see if there is data in the event buffer. More...
int	readEvent (void *buf)
	Reads one event from the event buffer (if data is present) and returns the number of BYTES read into the buffer. More...
int	readEvent (DAQWordBuffer &wbuf, int offset)
	Reads one event from the event buffer (if data is present) and returns the number of 16-BIT WORDS read into the buffer. More...
int	readEvent (DAQWordBufferPtr &wp)
	Reads one event from the event buffer (if data is present) and returns the number of 16-BIT WORDS read into the buffer. More...
int	readEvent (DAQDWordBuffer &dwbuf, int offset)
	Reads one event from the event buffer (if data is present) and returns the number of 32-BIT DWORDS read into the buffer. More...
int	readEvent (DAQDWordBufferPtr &dwp)
	Reads one event from the event buffer (if data is present) and returns the number of 32-BIT DWORDS read into the buffer. More...
Protected Methods
int	slotInit (int slotNum, int crateNum)
	Called by the constructor to initialize a card in a given slot. (should probably be broken into multiple functions...). More...
void	destruct ()
	Called by the destructor to free the resources associated with an allocated card. More...
Protected Attributes
int	slot
	This is the only member varaiable that is created with each instance of the class. More...
Static Protected Attributes
CAENcrate	crate [VME_CRATE_SIZE+1]
	This member holds all of the information on the current instances of CAENcards. More...
Friends
class	CAENchain
	Allows multiple contiguous cards to be accessed as one object.
bool	operator< (const CAENcard &, const CAENcard &)
	Compares the slot numbers to determine if the first is less. More...

---

Detailed Description

Drivers for the CAEN V775 TDC, V785 ADC, and V792 QDC modules.

Please note that these drivers have not yet been tested with the V792 QDC as I do not have access to one. Also, currently the initializer checks to see if the card is board version 3 or 4 and bios version 3 or 5. The drivers have only been tested with these versions of the cards. We recommend, however, that you ask your dealer to upgrade your cards to the latest bios revision as we have noticed issues with a version 3 card.

So far no adverse effects have been noticed if the optimize option is used on the compiler, so optimize away!

If you have a specific question or request email Chris Maurice at <maurice@nscl.msu.edu> and I will do my best to help.

---

Constructor & Destructor Documentation

CAENcard::CAENcard (  int slotNum = 0, int crateNum = 0 )

Standard constructor. SlotNum is required to create a valid card, crateNum is not. Parameters: slotNum   This specifies the slot in the VME crate in which the module resides. This value will be the first five bits of every 32-bit word in the output buffer. crateNum   An optional value that the module will write into the header of each event/block of data. May be useful to differential between different cards. The Default value is zero. If slotNum is not specified, or if it is outside the range of valid values then the function returns a "NULL" card. If the card cannot be initialized (wrong version of card, no card in slot) then the function returns a card which will be recognized as invalid by the other functions. Once the card is verified to be in the slot, one of the supported types, and if it is not currently referenced by another instance then it is reset to clear any previous settings. Also, the thresholds are also set to default values and the TDC is set to common-start mode.

CAENcard::CAENcard (  const CAENcard & card )

Another constructor. Allows a card to be created using another card. Parameters: card   The card to copy. The new CAENcard object will not cause the module to be reset, as this only happens the first time that a CAENcard object is created that refers to a given slot. This means that any settings that you have set on the card in that slot will not be lost. Also understand that the destination argument now points to the same card in the crate, and therefore any changes to either instance will be reflected in all other instances referring to the same card.

CAENcard::~CAENcard (  )

Reference counted destructor. The cards are not de-allocated until there are no references to them. The reference count of the slot number is decreased and then the destruct() function is called. If the reference count is less than one then the items in CAENcard::crate[slot] are destroyed. (memory map unmapped, file descriptor closed, status set to uninitialized)

---

Member Function Documentation

void CAENcard::cardOff (  )

Prevents the card from performing convertions until cardOn() or reset() is called. This function forces the module into offline mode so that no new data is produced. Data may still be present in the event buffer, however. This setting is cleared when reset() is called.

void CAENcard::cardOn (  )

Puts the card into online mode. (default) This function is not needed unless cardOff() has been previously called. The event buffer may still have data in it from events that were converted before cardOff() was called. This setting is cleared when reset() is called.

int CAENcard::cardType (  )

Returns the module number of the card in the slot. Returns: If the call succeeds then either 775, 785, or 792 will be returned as an integer. If the call fails (if it is called on an uninitialized card) then -1 will be returned.

void CAENcard::channelOff (  int ch )

Prevents the module from saving any conversions for the specified channel in the event buffer. Parameters: ch   The channel to suppress. A value of -1 indicates that all channels will be supressed. The kill bit in the threshold memory for the channel is set without destroying the threshold values. Call clearData() to ensure that all data in the event buffer reflects this change. The kill bit is not cleared by clearData() or reset(). Performing a hardware reset will clear the values, but there is no default value defined. The constructor does ensure that all channels are on, however.

void CAENcard::channelOn (  int ch )

Makes sure that the module can save conversions for the specified channel. Parameters: ch   The channel to unsuppress. A value of -1 indicates that all channels will be unsupressed. The kill bit in the threshold memory for the channel is cleared without destroying the threshold values. Call clearData() to ensure that all data in the event buffer reflects this change. An overflow, under threshold, or invalid data condition can still cause the channel to be supressed. The kill bit is not cleared by clearData() or reset(). Performing a hardware reset will clear the values, but there is no default value defined. The constructor does ensure that all channels are on, however.

void CAENcard::clearData (  )

Clears all data from the event buffer and usually the event counter, too (if not in "count all triggers" mode). No settings on the module are altered by this call.

int CAENcard::commonStart (  )

Sets the TDC to run in common start mode. Returns: Zero indicates a successful write while -1 indicates that either the card is not a TDC or it is not yet initialized. This setting is cleared by a call to reset(). When the card is first created it is set to use common start mode.

int CAENcard::commonStop (  )

Sets the TDC to run in common stop mode. Returns: Zero indicates a successful write while -1 indicates that either the card is not a TDC or it is not yet initialized. This setting is cleared by a call to reset(). The TDC has slightly better minimum detectable signal in this mode.

int CAENcard::dataPresent (  )

A simple test to see if there is data in the event buffer. Returns: 1 indicates that there is data in the event buffer 0 indicates that the event buffer is empty -1 is returned when the card has not been initialized This function is called by all of the readEvent functions before they read any data.

void CAENcard::destruct (  )  [protected]

Called by the destructor to free the resources associated with an allocated card. The calling function for this function must decrement value of CAENcard::crate[slot].refCount before calling this function (if appropriate). The memory map and file descriptor associated with this slot will be released and closed, respectively. The status of the slot is then set to be uninitialized.

int CAENcard::discardInvalidData (  )

Instructs the module to discard all conversions performed while the TDC is reseting. (default). Returns: Zero indicates a successful write while -1 indicates that either the card is not a TDC or it is not yet initialized. This setting is cleared if reset() is called. The default behavior is for the TDC to discard the invalid data.

void CAENcard::discardOverflowData (  )

Instructs the module to discard all conversions that overflow. (default). This setting is cleared if reset() is called. The default value is to dicard the conversions that result in an overflow.

void CAENcard::discardUnderThresholdData (  )

Instructs the module to discard all under threshold conversions. (default). This setting is cleared if reset() is called. The default value is to dicard the under threshold conversions.

int CAENcard::getCrate (  )

Returns an integer containing the current crate value. Returns: The current crate number is returned if the value is successfully read from the card. If the card is not in CAEN_MODE_A32D16 then the call will fail and return -1. This eight-bit value is set when the board is initialized (default value is zero). The value appears in the header of each event sent back from the card and is only useful to differentiate between the data from different cards. This value is not cleared by a call to dataClear(), but is cleared by a call to reset().

int CAENcard::keepInvalidData (  )

Allows conversions that take place while the TDC is reseting to be kept. Returns: Zero indicates a successful write while -1 indicates that either the card is not a TDC or it is not yet initialized. The invalid data bit is set when a stop signal is received while the TDC is reseting (it takes 700ns to reset) after the maximum conversion time das been hit. This setting is cleared when reset() is called.

void CAENcard::keepOverflowData (  )

Allows conversions that resulted in an overflow to be kept. Any conversions that result in an overflow condition cause the overflow bit to be set in the channel data. This setting is cleared when reset() is called.

void CAENcard::keepUnderThresholdData (  )

Allows conversions that resulted in under threshold values to be retained. Any under threshold data that is kept in the event buffer has the under-threshold bit set in the channel data. This setting is cleared when reset() is called.

CAENcard & CAENcard::operator= (  const CAENcard & card )

The card being assigned to has the destructor called on it and the value of the other argument assigned to it. Parameters: card   The CAENcard value to assign to the destination argument. Returns: The value placed into the destination argument. The new CAENcard object will not cause the module to be reset, as this only happens the first time that a CAENcard object is created that refers to a given slot. This means that any settings that you have set on the card in that slot will not be lost. Also understand that the destination argument now points to the same card in the crate, and therefore any changes to either instance will be reflected in all other instances referring to the same card.

int CAENcard::readEvent (  DAQDWordBufferPtr & dwp )

Reads one event from the event buffer (if data is present) and returns the number of 32-BIT DWORDS read into the buffer. Parameters: wp   A pointer to a DAQDWordBuffer object. Returns: > 0 indicates the number of 32-BIT WORDS of data placed in buf 0 indicates that no data was placed in the buffer -1 is returned if the card is not properly initialized Be careful about putting this function into a loop because it can return a negative value. Note that the standard readout skeleton does not provide you with a DAQDWordBuffer. Also make sure that the pointer does not point to a location that already contains data. Under normal conditions the readEvent(DAQDWordBuffer& dwbuf, int offset) fuction is much easier and intuitive to use.

int CAENcard::readEvent (  DAQDWordBuffer & dwbuf, int offset )

Reads one event from the event buffer (if data is present) and returns the number of 32-BIT DWORDS read into the buffer. Parameters: dwbuf   A DAQDWordBuffer object to put data in. offset   The position that the data should be written to. This is necessary to avoid overwriting other data in the DAQDWordBuffer. Returns: > 0 indicates the number of 32-BIT DWORDS of data placed in dwbuf 0 indicates that no data was placed in the buffer -1 is returned if the card is not properly initialized Be careful about putting this function into a loop because it can return a negative value. Note that the standard readout skeleton does not provide you with a DAQDWordBuffer.

int CAENcard::readEvent (  DAQWordBufferPtr & wp )

Reads one event from the event buffer (if data is present) and returns the number of 16-BIT WORDS read into the buffer. Parameters: wp   A DAQWordBufferPtr object. Returns: > 0 indicates the number of 16-BIT WORDS of data placed in buf 0 indicates that no data was placed in the buffer -1 is returned if the card is not properly initialized Be careful about putting this function into a loop because it can return a negative value. Also make sure that the pointer does not point to a location that already contains data. Under normal conditions the readEvent(DAQWordBuffer& wbuf, int offset) fuction is much easier and intuitive to use.

int CAENcard::readEvent (  DAQWordBuffer & wbuf, int offset )

Reads one event from the event buffer (if data is present) and returns the number of 16-BIT WORDS read into the buffer. Parameters: wbuf   A DAQWordBuffer object to put data in. When using the standard readout skeleton this object is created for you. offset   The position that the data should be written to. This is necessary to avoid overwriting other data in the DAQWordBuffer. Returns: > 0 indicates the number of 16-BIT WORDS of data placed in wbuf 0 indicates that no data was placed in the buffer -1 is returned if the card is not properly initialized Be careful about putting this function into a loop because it can return a negative value.

int CAENcard::readEvent (  void * buf )

Reads one event from the event buffer (if data is present) and returns the number of BYTES read into the buffer. Parameters: buf   A pointer to local memory that has already been allocated. Should be at least 34 * 4 = 136 bytes to hold the header, footer, and 32 channels of data. Returns: > 0 indicates the number of BYTES of data placed in buf 0 indicates that no data was placed in the buffer -1 is returned if the card is not properly initialized Be careful about putting this function into a loop because it can return a negative value.

void CAENcard::reset (  )

Clears all data from the buffer and clears most settings (they are set to default values by the card)v. This call does not change the threshold values or any of the settings that might disrupt communication with the module. This call does set the module to discard under threshold, overflow, and invalid data. Also the crate value is set to zero. Finally, the range, pedestal current, and start mode are all set to default values which are, unfortunately, not specified by the documentation.

void CAENcard::resetEventCounter (  )

Resets the value in the event counter to zero. Only the event counter (present in the End Of Block of every event) is affected by this call.

void CAENcard::setCrate (  int crateNum )

Sets the crate value that appears in the header of each data event. This eight-bit value is set when the board is initialized (default value is zero). The value appears in the header of each event sent back from the card and is only useful to differentiate between the data from different cards. This value is cleared by a call to reset().

int CAENcard::setPedestalCurrent (  int ped )

Sets the pedestal current and resolution on a QDC. Parameters: ped   A raw value to set the pedestal current on the QDC with. I do not have a QDC to test and the documentation is unclear to me. For larger values, however, the gate width also affects the channels' offsets. Returns: Zero indicates a successful write while -1 indicates that either the card is not a QDC or it is not yet initialized. This setting is cleared when reset() is called. No default value is set when the card is initialized.

int CAENcard::setRange (  int range )

Sets the range on a TDC (from 140 to 1200 ns). Parameters: range   A raw value used to set the range on the TDC with. -0x1E (30) sets the range to 1200ns -0xFF (255) sets the range to 140ns -Use linear iterpolation for intermediate values. Returns: Zero indicates a successful write while -1 indicates that either the card is not a TDC or it is not yet initialized and -2 indicates that an invalid value was passed. This setting is cleared by a call to reset(). The constructor defaults the range to 140ns.

void CAENcard::setThreshold (  int ch, int threshold )

Changes the raw 12-bit threshold value on any card. Parameters: ch   The channel on which to set the threshold. Use a value of -1 to set the threshold of all channels on the card. threshold   The low 12-bits of this value are used to set the threshold on the desired channels. The threshold value is compared against each converted value. If the converted value is less than the threshold then it is either discarded or, if the card is set to keepUnderThresholdData() then the underflow bit in the data word is set and it is stored in the event buffer. This function preserves the state of the kill bit in threshold memory so that it does not "turn on" any channels that have had channelOff() called on them. Thresholds are not cleared by clearData() or reset(). Performing a hardware reset will clear the thresholds, but there are no default values defined. The constructor does set all thresholds to reasonable defaults, however.

int CAENcard::setThresholdVoltage (  int ch, double voltage )

Sets the threshold on the 785 ADC based upon the specified voltage value. Parameters: ch   The channel on which to set the threshold. Use a value of -1 to set the threshold of all channels on the card. voltage   The approximate voltage to which the threshold is to be set. The conversion has a resolution of approximately 0.016 volts. This function only works if the card is a V785 ADC since it does not make sense to speak in terms of voltage thresholds with the TDC or QDC.

int CAENcard::slotInit (  int slotNum, int crateNum )  [protected]

Called by the constructor to initialize a card in a given slot. (should probably be broken into multiple functions...). Parameters: slotNum   This specifies the slot in the VME crate in which the module resides. This value will be the first five bits of every 32-bit word in the output buffer. crateNum   An optional value that the module will write into the header of each event/block of data. May be useful to differential between different cards. Returns: Failure to initialize the card is indicated by a return value less than zero. Each failure returns a different value and are numbered sequentially through the function. The calling function must increment the value of CAENcard::crate[slot].refCount after calling this function (if appropriate). The memory map and file descriptor associated with this slot will be allocated and opened, respectively, if not already present. The status of the slot is then set to be CAEN_MODE_A32D16 if successful.

---

Friends And Related Function Documentation

bool operator< (  const CAENcard & card1, const CAENcard & card2 )  [friend]

Compares the slot numbers to determine if the first is less. Not likely to be of any use except to allow the cards to be used in an STL class.

---

Member Data Documentation

CAENcrate CAENcard::crate[VME_CRATE_SIZE + 1] [static, protected]

This member holds all of the information on the current instances of CAENcards. The array holds a reference counted list of all of the currently initialized cards. index zero, aka. crate[0], is used to specify that the instance of a CAENcard has not been initialized to a slot (ie. a NULL CAENcard). Only one array is created no matter how many of the instances of the class are created, so any instances that are created with the same slot number will reference the the same physical card and the same entry in the crate array.

int CAENcard::slot [protected]

This is the only member varaiable that is created with each instance of the class. This variable is used as a reference into the static CAENcrate instance crate. It holds the reference counted information needed to access the card. The value is not zero indexed, so a value of 1 refers to the card in the physical slot number 1. A value of zero is reserved for uninitialized cards.

---

The documentation for this class was generated from the following files:

• CAENcard.h
• CAENcard.cpp

---