/*! \page page0 Configuration Data Management

	(Author of this document is Anders Ryd
	and the original can found in the DocDB as 
	document number <a href="https://docdb.fnal.gov/CMS-private/DocDB/ShowDocument?docid=1672">1672</a>).
	
	This document describes a C++ interface
	for configuration data management and the
	different classes that are used to store this
	information. 

	The idea behind this organization should be
	explained here. For now I just add a pointer
	to a presentation I gave at a pixel software
	meeting that contains the ideas:
	<pre>
	http://indico.cern.ch/conferenceDisplay.py?confId=8768
	</pre>
	
	The following arguments are treated in this document:
	
	<ul>
	 <li> \ref page1 
	 <li> \ref page2 
	 <li> \ref page3 
	 <li> \ref page4 
	</ul>
    
    __________________________________________________________________________________
    \page page1 1- Configuration Database Interface
 
 	Since early summer 2006 we have used an interface for accessing
	configuration data in the online software framework. 
	The access is currently file based. The 
	interface used is rather generic and the purpose of this document
	is to write down the interface so that we can have a 
	clear separation between the database code and the applications 
	that use data from the configuration database.

	First in Sect.~\\ref{sect:cppinterface} we describe the C++ API.
	The interface is defined in the class PixelConfigInterface.
	This interface is fully implemented in the PixelConfigFile 
	implementation based on files.

	In Sect. xx a simple command line tool is described.
	This tool is implemented through the C++ interface and should work
	both for the file based and the final data base implementation.

	Examples below use a few of the configuration data classes
	that are used. In Sect. yy the full
	set of classes that are used to configure and control the pixel
	online software are discussed.

      \section page1Sect1 C++ Configuration Data Access API

	The class PixelConfigInterface in the package 
	PixelConfigDBInterface defines the interface for
	access of configuration data. This interface is intended
	to provide type safe access methods for retrieving and
	storing configuration data.

      \subsection page1Sect1Sub1 Retrieving data from the database

	The primary method for retrieving the data is

	<pre>
	  template <class T>
	     static void get(T* &pixelObject,
	     		     std::string path,
	     		     pos::PixelConfigKey key)
	</pre>

	The PixelConfigKey is just an integer that holds the top
	level configuration key to be used. 
	This interface returns a pointer to the data. The caller is assumed
	to take ownership of the data and delete it. 
	The path is a 'secondary key'. It would allow us to store more than
	one object of the same type in a given configuration. (In the file
	based implementation this label is used to build the path to were the
	file is stored.)
	Below are a few example of using this interface.
	<pre>

	  PixelConfigKey theGlobalKey(5);

	  PixelNameTranslation *theNameTranslation=0;
	  PixelConfigInterface::get(theNameTranslation, "nametranslation/", 
                	     theGlobalKey);

	  PixelDetectorConfig *theDetectorConfiguration=0;
	  PixelConfigInterface::get(theDetectorConfiguration, "detconfig/", 
                	     theGlobalKey);

	  PixelFECConfig *theFECConfiguration=0;
	  PixelConfigInterface::get(theFECConfiguration, "fecconfig/", 
                	     theGlobalKey);

	</pre>

	These examples show how you extract objects for which there is only one 
	instance of for the
	whole detector configuration. You pass in as the first argument a pointer. The 
	pointer will return 0 if the object was not successfully retrieved. The
	second argument is the label for the object. This is essentially a key that
	is used to look up the data. The interface is type safe, i.e., if you specify 
	a path to an object of the wrong type you will get back a null pointer. The
	third argument is the global configuration key. This basically specifies 
	the versions of all objects used in a given configuration. This key is
	implemented as an integer.

	Besides objects like the name translation and detector configuration listed
	above, there are objects such as trim bits, mask bits, and dac values 
	that we need
	to access on a finer granularity than for the whole detector. To do this
	we use slightly modified arguments

	<pre>
	  PixelDACSettings *tempDACs=0;
	  PixelConfigInterface::get(tempDACs,''pixel/dac/FPix_BpI_D1_BLD1_PNL1'', 
                	     theGlobalKey);
	</pre>

	where we have added to the path the module name for which we want to 
	extract the
	dac settings.

	As a given application, for example the PixelFECSupervisor, will need to access
	dac settings for many modules, and it is more efficient to extract
	the data 'in bulk' from the database, we have also added an interface
	that allows extraction of multiple objects at the time

	<pre>
	  std::map<std::string, PixelDACSettings*> dacs;
	  dacs["pixel/dac/FPix_BpI_D1_BLD1_PNL1"]=0;
	  dacs["pixel/dac/FPix_BpI_D1_BLD1_PNL2"]=0;
	  PixelConfigInterface::get(dacs, theGlobalKey);
	</pre>

	The method will add pointers to the modules; if a module is not
	in the configuration a null pointer is returned.

	In addition to the access method that uses the configuration key,
	you can also retrieve data based on the specific version of the
	object
	<pre>
	  template <class T>
	  static void get(T* &pixelObject,
                	  std::string path,
			  unsigned int version)
	</pre>
	There is also a version that retrieves all the objects
	<pre>
	  template <class T>
	  static void get(std::map<std::string, T*> &pixelObjects,
			  unsigned int version)
	</pre>
	In general the access based on the configuration key should be used
	in the xdaq applications.


      \subsection page1Sect1Sub2 Storing data in the database

	To store data in the configuration database use the following 
	method

	<pre>
	  template <class T>
	  int PixelConfigInterface::put(const T* ,std::string path);
	</pre>

	This method will install the data in T* using the specified path.
	The new version number is returned by the method.
	If you instead have a set of configuration data that needs to be
	installed you use the interface

	<pre>
	  template <class T>
	  int PixelConfigInterface::put(std::vector<T*>,
                                	std::string path);
	</pre>

	Where a vector of pairs is passed, the second argument in the
	pair is the sub path used for the object.

      \subsection page1Sect1Sub3 Configuration keys

	A configuration key consists of a set of objects and their versions.
	The simplest form is just to specify a list of the paths and the 
	versions to use in the key
	<pre>
	  static unsigned int makeKey(std::vector<
                        	      std::pair<std::string, unsigned int> > versions)
	</pre>
	The method returns the new configuration key.

      \subsection page1Sect1Sub4 Alias manipulation

	For configurations aliases you can retrieve the list of defined 
	aliases using
	<pre>
	  static std::vector<std::pair<std::string, unsigned int> > getAliases()
	</pre>
	The string is the name of the alias and the unsigned int is the 
	corresponding key. <i>I think it should actually be a PixelConfigKey.</i>

	A very similar method is
	<pre>
	static std::map<std::string, unsigned int> getAliases_map()
	</pre>
	That returns a map between the alias name and the corresponding key.

	The method
	<pre>
	static void addAlias(std::string alias, unsigned int key)
	</pre>
	inserts a new alias. Note that if the alias already exists it will
	just be updated to point to the new key. 

	The method below is a lower level method. This method
	allows you to define an alias to a version that has key
	already created and link it to version aliases. This method
	should eventually be removed as it is probably to error prone...
	<pre>
	  static void addAlias(std::string alias, 
                	       unsigned int key,
			       std::vector<std::pair<std::string, std::string> > versionaliases)
	</pre>

	To create an alias for a configuration object use the method.
	<pre>
	    static void addVersionAlias(std::string path, 
                                	unsigned int version, 
                                	std::string alias)
	</pre>

	To add an alias for a configuration object, as supposed to a
	configuration key, use

	<pre>
	  static void addVersionAlias(std::string path,
                        	      unsigned int version, 
                        	       std::string alias)
	</pre>


	To get the actual version that an alias points to use the method
	<pre>
	  static unsigned int getVersion(std::string path,
                                	 std::string alias)
	</pre>
  
    \subsection page1Sect1Sub5 Support of polymorphism

	The interface should support polymorphism in the sense described
	below. For example, for trim bits it may be convenient to have ways of
	storing the trim bits in different ways. We will need to be able 
	to store trim bits so that we can set them independently for
	each pixel. But there are other cases where we might want to set
	all trim bits the same on a whole ROC, or the same in each 
	double column.

	Consider that we have a base class, PixelTrimBase and that there
	are the concrete implementations PixelTrimAll, PixelTrimROC,
	and PixelTrimDCol which implements the per pixel, per roc, and
	per double column respectively. The interface should support
	operations like

	<pre>
	  PixelTrimBase *tempTrims=0;
	  PixelConfigInterface::get(tempTrims,"pixel/trim/FPix_BpI_D1_BLD1_PNL1", 
                	     theGlobalKey);
	</pre>

	where after tempTrims points to the data type stored in the 
	database for the configuration.

	Similarly you should be able to store data

	<pre>
	  PixelTrimBase *tempTrims=new PixelTrimROC; //probably would not compile as
                                        	     //we don't have this constructor.
	  unsigned int ver=PixelConfigInterface::put(tempTrims,"pixel/trim/FPix_BpI_D1_BLD1_PNL1");
	</pre>


      \section page1Sect2 Command line interface to configuration data

	Based on the interface described above in the C++ interface a simple
	command line tool has been written to allow manipulation of configuration
	data. The functionality of this interface is described below.

      \subsection page1Sect2Sub1 Inserting new data

	Here we will start be discussing how you insert a
	PixelDetectorConfig object. There is
	only one such object in the configuration. Assuming that we
	have this in a file named <tt><b>detconfig.dat</b></tt>. We now want to
	insert this into the configuration database. This is done with

	<pre>
	PixelConfigDBCmd.exe --insertData detconfig detectconfig.dat
	</pre>
	This would install the content of the file <tt><b>detconfig.dat</b></tt> 
	under the path <tt><b>detconfig</b></tt> by creating a new version.
	This new version is returned by the command so that it is known
	where it was installed. The implementation of this tool
	reads the file to create a PixelDetectorConfig object and
	then uses the C++ interface to store the data.

	As a variation of this you might want to install, e.g., a new set of 
	DAC settings for the ROCs. As we insist that no data can be 
	changed in the configuration database after it has been loaded
	this implies that the DAC settings for all ROCs needs to be
	loaded at once. To insert that prepare the files that contains the
	ROC dac settings. Then create the file daclist.txt that list all
	the file that you want to install. To install them into the
	database us

	<pre>
	PixelConfigDBCmd.exe --insertDataSet dac daclist.txt
	</pre>

	Again a new version has been created under the path <tt><b>dac</b></tt> and
	all the dac settings have been uploaded. The new version is then
	printed out.

	Note that these interfaces are designed to not allow
	you to change any existing data. (We might want to consider allowing
	adding comments to existing versions of configuration data.)

      \subsection page1Sect2Sub2 Retrieving data

	From the command line you can retrieve data using
	<pre>
	PixelConfigDBCmd.exe --getVersion nametranslation/ 0
	</pre>
	This will retrieve the data from version 0 of the nametranslation 
	and write it out as a file.

      \subsection page1Sect2Sub3 Creating new configurations

	So far we have discussed how to add new data to the configuration
	database. The next step is to combine versions of several 
	data types into a configuration. This is done with a command 
	like

	<pre>
	PixelConfigDBCmd.exe --insertConfigAlias Physics dac 1 detconfig 0 nametranslation 0
	</pre>

	where the versions of the different objects on the paths are 
	listed. This will create a new configuration key. This key will
	be returned by the command. 

	Very often we have an existing configuration, <tt><b>oldKey</b></tt>, that
	we want to 'update'. Note that update actually means that we will create
	a new configuration. For example you can do
	<pre>
	PixelConfigDBCommand --updateConfigAlias 5  tbm 6
	</pre>
	<i>not yet implemented.</i> So in the example above a copy of 
	configuration key number 5 would
	be made in which the TBM settings version 6 was added.

	If one wants to remove an existing object from a configuration
	we could imagine doing something like
	<pre>
	PixelConfigDBCommand --updateConfigAlias 5  calib -1
	</pre>

	In both these cases the new configuration key that was created is
	returned. Again this interface guarantees that no existing 
	data has been changed. Only new data has been added.

      \subsection page1Sect2Sub4 Alias manipulation

	The simplest use case is that we can create an alias that points
	to a specific key. This could e.g. be to point the 'Physics' 
	alias to configuration key 5
	<pre>
	PixelConfigDBCommand --insertConfigAlias Physics 5
	</pre>

	But we need to expand on this to make it more manageable
	to handle the configurations.

	In addition to have aliases for the toplevel configurations
	we can define aliases for the configuration data versions.
	For example you can define the 'Physics' alias for the TBM settings
	version 4 using
	<pre>
	PixelConfigDBCommand --insertVersionAlias tbm 4 Default
	</pre>
	Very similar to the --createconfig from above you
	can also do
	<pre>
	PixelConfigDBCommand --insertConfigAlias Physics dac 5 detconfig 3 tbm Physics
	</pre>
	This will create a new toplevel configuration key and the 
	alias 'Physics' will point to this key. Say that you then also do
	<pre>
	PixelConfigDBCommand --insertConfigAlias PhysicsLowLumi dac 4 detconfig 3 tbm Physics
	</pre>
	We have now  created two aliases to two toplevel keys. Now, if you 
	do
	<pre>
	PixelConfigDBCommand --insertVersionAlias tbm 5 Physics
	</pre>
	this should automatically create two new toplevel configurations
	for 'Physics' and 'PhysicsLowLumi'.

      \subsection page1Sect2Sub5 Use cases

	Below I will give some examples for how we could be using the
	capabilities discussed in the previous two sections. To simplify
	this a little bit I will work with a configuration that only
	has 4 different types of objects (detconfig, tbm, dac, and masks).

	The first thing we need to do is to load the configuration data.
	Assume that we do this on a completely empty database.

	<pre>
	PixelConfigDBCmd.exe --insertData fecconfig fecconfig.dat
	PixelConfigDBCmd.exe --insertData fedconfig fedconfig.dat
	PixelConfigDBCmd.exe --insertData tkfecconfig tkfecconfig.dat
	PixelConfigDBCmd.exe --insertData portcardmap portcardmap.dat
	PixelConfigDBCmd.exe --insertDataSet fedcard fedcardlist.txt
	PixelConfigDBCmd.exe --insertDataSet portcard portcardlist.txt
	PixelConfigDBCmd.exe --insertDataSet tbm tbmlist.txt
	PixelConfigDBCmd.exe --insertDataSet dac daclist.txt
	</pre>
	So now we have version 0 for each of these objects. Now I can
	create aliases for the different objects.

	<pre>
	PixelConfigDBCommand --insertVersionAlias detconfig 0 Physics
	PixelConfigDBCommand --insertVersionAlias tbm 0 Default
	PixelConfigDBCommand --insertVersionAlias dac 0 Default
	PixelConfigDBCommand --insertVersionAlias mask 0 Default
	</pre>

	<pre>
	PixelConfigDBCommand --insertConfigAlias Physics dac Default detconfig Physics
	tbm Default mask Default
	</pre>

	This command will create the first configuration key, number 0. Now
	say that a new set of dac settings is created and loaded:
	<pre>
	PixelConfigDBCommand --insertData dac daclist.txt 
	</pre>
	This will be version 1 of the dac settings. Next if you make this
	alias the 'Default':
	<pre>
	PixelConfigDBCommand --insertVersionAlias dac 1 Default
	</pre>
	The code will automatically update all toplevel aliases that are
	using this the 'Default' dac settings. In this example it
	means that the top level 'Physics' alias will point to key 1.

    __________________________________________________________________________________
    \page page2 2- Managing Configurations

	We need higher level tools to manage configurations. The way we 
	currently have the configurations implemented there are about 
	15 different objects that are needed to build a configuration.
	Two examples of such configurations are:

	<pre>
	key 0
	detconfig   2
	nametranslation   0
	fedconfig   0
	fecconfig   0
	fedcard   0
	dac   2
	mask   2
	trim   2
	calib   0
	tbm   0
	portcard   0
	portcardmap   0
	ttcciconfig 0
	tkfecconfig 0

	key 1
	detconfig   2
	nametranslation   0
	fedconfig   0
	fecconfig   0
	fedcard   0
	dac   2
	mask   2
	trim   2
	calib   8
	tbm   0
	portcard   0
	portcardmap   0
	ttcciconfig 0
	tkfecconfig 0
	</pre>

	For a moment I will not discuss the 'aliases', I will focus just
	on the data organization and the tools needed to manipulate the
	data. The different data types used in the configurations are 
	discussed in Sect.~\\ref{sect:configobjects}


      \section page2Sect1 Configuration DB Implementation

	To be added. Stay tuned.

    __________________________________________________________________________________
    \page page3 3- Configuration Objects

	This section describes the implementation
	of the configuration objects for the 
	pixel online system. The interface for accessing this data 
	was discussed in the previous section. 

      \section page3Sect1 Introduction

	Key goals for the design of the configuration
	data object include:
	<ul>
	<li> The configuration has to be fast and reliable.
	      The fewer components, read pieces of software, 
	      involved in the configuration step the more
	      likely the system is to work reliably.
	<li> The data volume should be small. I.e. the data
	      has to be packed in an efficient way.
	<li> Want to optimize the database access by accessing
	      relatively few, but large, objects. 
	<li> Computers are good at manipulating data that is in
	      memory, so the actual commands that are sent to 
	      the hardware can be built on the fly -- assuming that
	      all information to do this is accessible in memory.
	<li> The data volume for the whole pixel system is O(100MB)
	      so holding this in memory in a single computer should
	      not be an issue. In fact this will be spread over
	      more than one computer as the FECs are in more than
	      one crate.
	</ul>

	The following classes are used to configure the online pixel
	applications:

	
	
	PixelTrimAllPixels: This class stores the trim bits for the
        		     ROCs on one module. The trims are stored
        		     for each pixel.

	
	
	PixelMaskAllPixels: This class stores the mask bits for the
        		     ROCS on one module. The masks are stored
        		     for each pixel.

	
	
	PixelDACSettings: This class stores the DAC settings for all
        		   ROCs on one module. 

	
	
	PixelTBMSettings: This class stores the TBM settings for one
        		   TBM.

	
	
	PixelNameTranslation: This class translates from the pixel 
        		       naming scheme documents names of ROCs to
        		       the hardware addresses used by both the
        		       FEC and the FED to identify a ROC.

	
	
	PixelDetectorConfig: This class lists the modules used in a 
        		      configuration. The utility of this class
        		      is that it allows one to only use a small
        		      subset of the detector without having to 
        		      create a new name translation.

	
	
	PixelROCStatus: This class keeps track of the status of 
        		 ROCs. The default assumption is that a ROC
        		 is working and this object allows us to 
        		 list ROCs that are not working, or that we 
        		 want to turn off.

	
	
	PixelFECConfig: This class lists the pixel FECs that are used.

	
	
	PixelTKFECConfig: This class lists the tracker FECs that are used.

	
	
	PixelFEDConfig: This class lists the pixel FEDs that are used in
        		 the configuration.

	
	
	PixelFEDCard: This class stores the settings for one FED board.

	
	
	PixelPortCard: This class stores the settings on a portcard, e.g.
        		the delay25 settings and AOH settings.

	
	
	PixelPortcardMap: This class maps the AOH channels on portcards
        		   to the FED channels.


	
	
	PixelLTCConfiguration: This class holds the configuration for the 
        			pixel LTC module.
	
	
	PixelTTCciConfiguration: This class holds the configuration for the 
        			  pixel TTCci module.

	
	
	PixelCalibConfiguration: This class specifies how the calibrations
        			  are executed. 

	
	
	PixelDelay25Configuration: This class specifies how the delay25 
                                	 calibration is executed.

	


	With the exception of PixelCalibConfiguration and 
	PixelDelay25Configuration the classes above are used to build the
	configuration of the hardware. The last two classes are used to 
	configure the software applications to perform a given 
	calibration.


	The following sections describe what is implemented, starting with
	a common base class for all configuration objects and then a
	brief discussion of all classes currently implemented.

	All configuration objects derive from a common base class called
	PixelConfigBase.

	<pre>
	class PixelConfigBase {

	 public:

	    //A few things that you should provide
	    //description : purpose of this object
	    //creator : who created this configuration object
	    //date : time/date of creation (should probably not be
	    //       a string, but I have no idea what CMS uses.
	    PixelConfigBase(std::string description,
			    std::string creator,
                	    std::string date);

	    virtual ~PixelConfigBase(){}

	    std::string description();
	    std::string creator();
	    std::string date();

	    //Interface to write out data to ascii file
	    virtual void writeASCII(std::string dir="") const = 0;

	 private:

	    std::string description_;
	    std::string creator_;
	    std::string date_;


	};
	</pre>

	This class is intended to provide a common interface. Currently it simply
	holds information about when the objects were created. 

      \section page3Sect2 Trim and mask bits

	The trim and mask bits need to be set for each pixel. This
	makes these the largest configuration objects. In terms
	of configuration of the ROC, the mask and trim bits are loaded
	together. However, as the mask bits are used offline we will
	store the trim and mask bits in different objects 
	as this will reduce the data that needs to be downloaded
	to access the mask bits offline. Also, this saves space
	as compared to storing the trim and mask bit for each 
	channel as one byte. It is also likely that we would
	like to update the mask bits without changing the trim bits.
	This would happen for example when we discover a hot pixel
	and want to mask it off. Being able to change only the
	mask bits would then be useful.

	For both the mask and trim bits we allow for different implementations.
	For example, we can have one implementation that allows us
	to use different settings for each pixel, or we can have a different
	configuration that uses the same settings for all pixels. The code
	handle this transparently by using inheritance. 

	For the mask bits the base class looks like:

	<pre>
	class PixelMaskBase: public PixelConfigBase {

	 public:

	    PixelMaskBase(std::string description, 
			  std::string creator,
			  std::string date);

	    virtual ~PixelMaskBase();

	    void setOverride(PixelMaskOverrideBase*);

	    virtual const PixelROCMaskBits& getMaskBits(int ROCId) const =0;

	    virtual void writeBinary(std::string filename) const =0;

	    virtual void writeASCII(std::string filename) const =0;

	    friend std::ostream& operator<<(std::ostream& s, const PixelMaskBase& mask);

	 private:

	    //Hold pointer to the mask override information.
	    PixelMaskOverrideBase* maskOverride_;


	};
	</pre>

	The concrete implementation that implements mask bits for each
	channel looks like:

	<pre>
	class PixelMaskAllPixels: public PixelMaskBase {

	 public:

	    PixelMaskAllPixels(std::string filename);

	    void writeBinary(std::string filename) const;

	    void writeASCII(std::string filename) const;

	    const PixelROCMaskBits& getMaskBits(int ROCId) const;

	 private:

	    std::vector<PixelROCMaskBits> maskbits_;  

	};

	</pre>

	The file format that we use looks like:
	<pre>
	ROC:     FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC1
	col00:   11110000000000000000000000000000000000000000000000000000000000000000000000000000
	col01:   00000000000000000000000000000000000000000000000000000000000000000000000000000000
	col02:   00000000000000000000000000000000000000000000000000000000000000000000000000000000
	---
	---
	---
	col49:   00000000000000000000000000000000000000000000000000000000000000000000000000000000
	col50:   00000000000000000000000000000000000000000000000000000000000000000000000000000000
	col51:   00000000000000000000000000000000000000000000000000000000000000000000000000000000
	ROC:     FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC2
	col00:   10000000000000000000000000000000000000000000000000000000000000000000000000000000
	col01:   20000000000000000000000000000000000000000000000000000000000000000000000000000000
	col02:   30000000000000000000000000000000000000000000000000000000000000000000000000000000
	---
	---
	---
	</pre>
	Where the file contains the data for each of the ROCs in a module.
	Within each ROC the trim bits are listed for each column by the
	value if the trim bit as one hexadecimal character from 0 to F.


	Similarly for the trim bits we have the base class:

	<pre>
	class PixelTrimBase: public PixelConfigBase {

	 public:

	    PixelTrimBase(std::string description, 
			  std::string creator,
			  std::string date);

	    virtual ~PixelTrimBase();

	    void setOverride(PixelTrimOverrideBase* trimOverride);

	    //Build the commands needed to configure ROCs
	    //on control link

	    virtual void generateConfiguration(PixelFECConfigInterface* pixelFEC,
					       PixelNameTranslation* trans,
					       const PixelMaskBase& pixelMask) const =0;
	    virtual void writeBinary(std::string filename) const =0;

	    virtual void writeASCII(std::string filename) const =0;

	    virtual PixelROCTrimBits getTrimBits(int ROCId) const =0;

	    friend std::ostream& operator<<(std::ostream& s, const PixelTrimBase& mask);


	 private:

	    PixelTrimOverrideBase* trimOverride_;

	};
	</pre>

	And the concrete implementation looks like:

	<pre>
	class PixelTrimAllPixels: public PixelTrimBase {

	 public:

	    PixelTrimAllPixels(std::string filename);

	    //Build the commands needed to configure ROCs
	    //on control link

	    void generateConfiguration(PixelFECConfigInterface* pixelFEC,
				       PixelNameTranslation* trans,
				       const PixelMaskBase& pixelMask) const;

	    void writeBinary(std::string filename) const;

	    void writeASCII(std::string filename) const;

	    PixelROCTrimBits getTrimBits(int ROCId) const;

	 private:

	    std::vector<std::string> rocname_;
	    std::vector<PixelROCTrimBits> trimbits_;

	};
	</pre>

	We use basically the same format for the mask bits as we used for the
	trim bits:

	<pre>
	ROC:    FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC1
	col00:  11111111111111111111111111111111111111111111111111111111111111111111111110000000
	col01:  11111111111111111111111111111111111111111111111111111111111111111111111111111111
	col02:  11111111111111111111111111111111111111111111111111111111111111111111111111111111
	---
	---
	---
	col49:  11111111111111111111111111111111111111111111111111111111111111111111111111111111
	col50:  11111111111111111111111111111111111111111111111111111111111111111111111111111111
	col51:  11111111111111111111111111111111111111111111111111111111111111111111111111111111
	ROC:    FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC2
	col00:  11111111111111111111111111111111111111111111111111111111111111111111111111111111
	col01:  11111111111111111111111111111111111111111111111111111111111111111111111111111111
	col02:  11111111111111111111111111111111111111111111111111111111111111111111111111111111
	---
	---
	.
	</pre>
	Here the mask bits are either 0 or 1 for each pixel.

      \section page3Sect3 ROC DACs

	The DAC settings for each readout chip are stored in the class

	<pre>
	class PixelDACSettings: public PixelConfigBase {

	 public:

	    PixelDACSettings(std::string filename);

	    PixelROCDACSettings getDACSettings(int ROCId) const;

	    //Generate the DAC settings
	    void generateConfiguration(PixelFECConfigInterface* pixelFEC,
	                	       PixelNameTranslation* trans) const; 

	    void writeBinary(std::string filename) const;

	    void writeASCII(std::string filename) const;

	    friend std::ostream& operator<<(std::ostream& s, const PixelDACSettings& mask);

	 private:

	    std::vector<PixelROCDACSettings> dacsettings_;   

	};

	</pre>
	The format for the DAC settings in the ASCII format is given by
	<pre>
	ROC:           FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC1
	Vdd:           6
	Vana:          140
	Vsf:           128
	Vcomp:         15
	Vleak_comp:    0
	VrgPr:         0
	VallPr:        35
	VrgSh:         0
	VwllSh:        35
	VHldDel:       90
	Vtrim:         29
	VthrComp:      70
	VIbias_Bus:    30
	Vbias_sf:      6
	VoffsetOp:     30
	VIbiasOp:      115
	VoffsetRO:     100
	VIon:          115
	VIbias_PH:     90
	VIbias_DAC:    100
	VIbias_ROC:    160
	VIColOr:       99
	Vnpix:         0
	VsumCol:       0
	VCal:          80
	CalDel:        90
	WBC:           120
	ChipContReg:   0
	ROC:           FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC2
	Vdd:           6
	Vana:          140
	Vsf:           128
	---
	---
	---
	</pre>
	Where the file contains the DAC settings for all the ROCs in a given module.

      \section page3Sect4 PixelDetectorConfig

	Specifies which components of the detector are used in the configuration.
	The level of configurability is the module (or in FPIX language 
	the panel). I.e. the
	components that are controlled by one TBM. <i>Currently this 
	controls which modules are configured. This should be enhanced to
	also control which FED channels are configured and what portcard
	devices are initialized.</i>

	The file format that we use to specify this format looks like:
	<pre>
	FPix_BmI_D1_BLD1_PNL1
	FPix_BmI_D1_BLD1_PNL2
	---
	---
	---
	</pre>

	The format above is the 'old' format. After discussions with the
	database GUI developers we have decided to make this object
	specify the ROC and their status. All ROCs on a module has
	to be listed. Otherwise there is an internal inconsistency in
	the configuration. In addition to listing the ROC one can
	specify a status of the ROC. An example of the file is
	given below
	<pre>
	Rocs:
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC0 
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC1 
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC2 off
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC3 
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC4 noHits
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC5 
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC6 off noHits
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC7 
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC8 
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC9 
	</pre>
	Currently the status words 'off' and 'noHits' are used.
	Off means that the chip is turned of for readout, i.e.
	that bit on of the chip controll register is set.
	noHits is a status of the ROC that means that this
	ROC is not generating hits. This for example means that
	you can not do an address level calibration and that 
	this information can be used to make sure that no
	errors are reported as it is known that this ROC is
	not working.


      \section page3Sect5 PixelROCStatus

	The <tt><b>PixelROCStatus</b></tt> class is used to store the status
	of ROCs. The default assumption is that a ROC is working and
	is on. However, we are likely to have problems with some ROCs
	given the number of components we have. This structure should
	allow us to add new failure modes as we discover new 
	problems. An example of the data would look like
	<pre>
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC2 NoHits
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC7 Off
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC8 Off NoHits
	</pre>

	The different status flags that we can set are:
	<ul>
	<li> <tt><b>NoHits</b></tt> indicates that we can not generate hits on the ROC.
	      for example this means that the ROC can not be calibrated e.g. for
	      address levels. However, it is not preventing us from doing the
	      UB equalization.
	<li> <tt><b>Off</b></tt> The is not used in any calibration and the roc is
                	turned off such that it will not generate hits.
                	However, even it a ROC is <tt><b>Off</b></tt> it will be
                	configured. 
	</ul>
	Note that we can set more than one of these flags at once. (Likely
	one would implement this as a bitmap.

      \section page3Sect6 PixelNameTranslation

	This class generates the translation between the names used in the 
	naming document and the hardware addresses. This includes both the
	FEC and the FED.

	The data format used for the name translation is given by:
	<pre>
	# name                          TBMchannel  FEC      mfec  mfecchannel hubaddress portadd rocid     FED     channel     roc#
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC0      A       1        8        1          31        0       0        1         12        0
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC1      A       1        8        1          31        0       1        1         12        1
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC2      A       1        8        1          31        0       2        1         12        2
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC3      A       1        8        1          31        0       3        1         12        3
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC4      A       1        8        1          31        0       4        1         12        4
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC5      A       1        8        1          31        0       5        1         12        5
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC6      A       1        8        1          31        0       6        1         12        6
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC7      A       1        8        1          31        0       7        1         12        7
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC8      A       1        8        1          31        0       8        1         12        8
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC9      A       1        8        1          31        0       9        1         12        9
	</pre>

	The name translation allows us to map the ROC name to the hardware addresses
	used in the configuration.

      \section page3Sect7 PixelFECConfig

	This class specifies the location of the pixel FECs. This
	basically gives the VME base address to use. An arbitrary FEC
	number is used here. <i>is this specified in the naming
	convention document?</i> Also we refer to the crate number here. 
	There will be one PixelFECSupervisor per crate. How is this
	number identified? The PixelFECSupervisor is initialized
	with a crate number and will control the FEC cards that are 
	in the crate.

	The file format that we have to store this information looks like
	<pre>
	#FEC number     crate     vme base address
	1               1         0x80000000
	</pre>
	Each FEC is identified by a number. The FEC is identified by the 
	crate and base address.

      \section page3Sect8 PixelTKFECConfig

	This class specifies the location of the tracker FECs in
	the system. This
	specifies the VME slot and crate used for each TKFEC board. An arbitrary TKFEC
	ID string is used here. <i>is this specified in the naming
	convention document?</i>
	There will be one PixelTKFECSupervisor per crate. 
	The PixelTKFECSupervisor is initialized
	with a crate number and will control the TKFEC cards that are 
	in the crate.

	The file format that we have to store this information looks like
	<pre>
	#TKFEC ID     crate     VME/PCI    slot/address
	tkfec1          1                     0x1c
	</pre>
	Each TKFEC is identified by an ID string. (Currently this string
	is arbitrary but we should use an agreed upon convention.)

	Optionally, to use a PCI TKFEC, the string ``PCI" may be added between
	the crate number and slot number.  ``VME" may also be specified.  If this
	parameter is not specified, it defaults to VME.


      \section page3Sect9 PixelFEDConfig

	This specifies how the FEDs are configured. This includes the FED
	number and the VME base address. The FED number is the same as
	the FED id in the Slink data. Each PixelFEDSupervisor is initialized
	with a crate number corresponding to the crate it controls.

	The file format that we have to store this information looks like
	<pre>
	#FED number     crate     vme base address
	1               1         0x1c000000
	</pre>
	Each FED is identified by a number, this is the same number as 
	the FED id in the raw data. The FED is identified by the 
	crate and base address. For now the crate is identified by an
	arbitrary number. <i>Should this be changed to the 
	actual name of the crate?</i>

      \section page3Sect10 PixelCalibConfiguration

	This class was formerly known as PixelCalib, but was renamed after
	it was moved to the CMSSW repository in order to make it more
	consistent with offline conventions.
	This class incorporates information about how a calibration
	is executed. In particular it handles calibrations where 
	groups of pixels have charge injects. It specifies how we loop over pixels
	and pulse the detector in a calibration. The class is also
	used in the offline in order to analyze the calibration data,
	so that we know what event had what charge injected and what
	pixel were expected to be hit. 

	Below is an example of this file:
	<pre>
	Mode: ThresholdCalDelay
	Rows:
	10 | 20 
	Cols:
	10 | 20
	VcalHigh
	Scan: VcThr 0 255 8
	Scan: CalDel 0 255 8
	Set: Vcal 50
	Repeat: 10
	Rocs:
	FPix_BmI_D1_BLD1_PNL1_PLQ1_ROC0
	FPix_BmI_D1_BLD1_PNL1_PLQ1_ROC1
	FPix_BmI_D1_BLD1_PNL1_PLQ2_ROC0
	FPix_BmI_D1_BLD1_PNL1_PLQ2_ROC1
	---
	---
	---
	</pre>

	Arbitrary parameters may be specified just before the ``Rows:" line.
	For example,
	<pre>
	Mode:  AOHBias
	Parameters:
	TargetBMin     412
	TargetBMax     612
	printFEDRawData             no
	printFEDOffsetAdjustments   no
	printAOHBiasAdjustments     no
	Rows:
	---
	---
	---
	</pre>
	These parameters are accessible in the calibration code.  Each calibration
	may look for particular parameters to control its operation.  Parameters
	not defined for a particular calibration are ignored.

	In particular the parameter ``ScanMode'' can be defined. It can take
	the three values of ``maskAllPixels'', ``useAllPixels'', and ``default''.
	In the default mode the trim and mask bits specified in the configuration 
	is used during the scan. Charge is injected according to the pattern
	and the pixels that are enabled in the configuration is used during
	the calibration. In the maskAllPixels mode all pixels are
	disabled before the first event. Then the pixels are enabled
	corresponding to the pixel mask and the pattern that has charged
	injected. I.e., only pixels that have charge injection and that
	are not disabled in the configuration will be enabled. The pixels
	use the trim bits from the configuration. In the useAllPixels mode
	all the pixels on the current pattern is enabled independently of
	what the mask bit is in the configuration if ScanMode is not 
	defined the mode useallPixels will be used.

	DACs to scan are selected with lines of the form.
	<pre>
	Scan: [DAC name] [min scan value] [max scan value] [scan step size] [mix]
	</pre>
	The last parameter is optional.  If nothing is given here, then all ROCs will be 
	set to the same DAC value at the same time.  If the word <b><tt>mix</tt></b> is placed here 
	(at the end of the line), then the ROCs on a particular channel will have not have
	 the same DAC value at the same time.  Instead, the DAC values on different ROCs 
	 will be spread out to cover the entire range.  This is useful when scanning 
	 <b><tt>Vsf</tt></b> or any other setting that affects the power drawn by the chip, 
	 as it prevents the ROCs from all drawing high power at the same time.

	The list of ROCs may be specified completely, or it may be auto-generated.  
	Auto-generation requires knowing which modules are in the configuration, and 
	which ROCs are on those modules.  Currently, this information is not 
	available in offline (i.e. CMSSW) code, so offline code must have the 
	ROC list specified completely.  To do this, the format is:
	<pre>
	Rocs:
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC0
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC1
	---
	---
	---
	</pre>
	In online running, where this information is available, it is preferable 
	to use auto-generation.  To auto-generate the list, the first line should 
	be ``<b><tt>ToCalibrate:</tt></b> instead of ``<b><tt>Rocs:</tt></b>".  (The user may 
	specify a complete ROC list with ``<b><tt>ToCalibrate:</tt></b>".  Compared to 
	using ``<b><tt>Rocs:</tt></b>", this has the advantage of not adding ROCs which 
	are not found in the configuration.  So it is always recommended to 
	use ``<b><tt>ToCalibrate:</tt></b>" if possible.)

	Probably the most common thing is to just add all ROCs and modules in 
	the configuration. This simply requires the word <b><tt>all</tt></b>:
	<pre>
	ToCalibrate:
	all
	</pre>

	To specify, say, just 2 ROCs, use:
	<pre>
	ToCalibrate:
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC0
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC1
	</pre>

	To specify, say, all the ROCs on just two modules, use:
	<pre>
	FPix_BpI_D1_BLD1_PNL1
	FPix_BpI_D1_BLD1_PNL2
	</pre>
	(The ROCs on each module are obtained from the name translation.)

	You can mix and match ROCs and modules:
	<pre>
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC0
	FPix_BpI_D1_BLD1_PNL2
	</pre>

	You can also exclude particular ROCs and modules by adding them with a 
	minus sign in front (separated by whitespace):
	<pre>
	ToCalibrate:
	all
	- FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC0
	- FPix_BpI_D1_BLD1_PNL2
	</pre>
	This fills the ROC list with all ROCs in the configuration, except 
	for <b><tt>FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC0</tt></b> and for all the ROCs 
	in <b><tt>FPix_BpI_D1_BLD1_PNL2</tt></b>.

	For another example:
	<pre>
	ToCalibrate:
	FPix_BpI_D1_BLD1_PNL1
	- FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC0
	</pre>
	This adds all ROCs on <b><tt>FPix_BpI_D1_BLD1_PNL1</tt></b> except 
	for <b><tt>FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC0</tt></b>.

	You may optionally add a ``<b><tt>+</tt></b>" in front of things that 
	you're adding. (If no ``<b><tt>+</tt></b>" or ``<b><tt>-</tt></b>" is seen, ``<b><tt>+</tt></b>" is 
	assumed.)
	<pre>
	ToCalibrate:
	+ all
	- FPix_BpI_D1_BLD1_PNL1
	+ FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC0
	</pre>
	This adds all ROCs on all modules, except 
	for <b><tt>FPix_BpI_D1_BLD1_PNL1</tt></b>, on which 
	only <b><tt>FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC0</tt></b> is added.

	Note that the order matters. The following:
	<pre>
	ToCalibrate:
	+ all
	+ FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC0
	- FPix_BpI_D1_BLD1_PNL1
	</pre>
	would not include <b><tt>FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC0</tt></b> in the 
	ROC list, because it is later removed by the 
	removal of <b><tt>FPix_BpI_D1_BLD1_PNL1</tt></b>.

	(For completeness, even though it's completely useless, you 
	can use ``<b><tt>- all</tt></b>" to clear the ROC list.)

	The auto-generated ROC list only adds ROCs on modules 
	given in the <b><tt>PixelDetectorConfig</tt></b>.

      \section page3Sect11 PixelFedCard

	The <tt><b>PixelFEDCard</b></tt> class contains the settings for a FED board.
	The file is fairly long and I do not include an example here. 
	You can find a sample file in PixelFEDInterface/test/params_fed.dat 
	<i> There is some information on the PixelFEDCard that is 
	redundant with the PixelFEDConfig like the VME base address. We
	should only specify this in one location.</i>

      \section page3Sect12 PixelTBMSettings

	This class holds the settings used by the TBM. The file contains the
	module name and gain settings as well as if the TBM should be
	configured in 'SingleMode' or 'DualMode'. 

	The format used for this information is given by
	<pre>
	FPix_BpI_D1_BLD1_PNL1_PLQ2_ROC1
	AnalogInputBias: 160
	AnalogOutputBias: 110
	AnalogOutputGain: 207
	Mode: SingleMode
	</pre>
	<i>Note that the name here should be a module name and not contain
	the plaquette and ROC number. We now have a 'PixelModuleName' class
	that we should use here.</i>


      \section page3Sect13 PixelPortcardMap

	This class lists the portcards used in the configuration
	and which fed channels are on which AOH.

	The format of this information is illustrated by the file:
	<pre>
	# PortcardName       Module                AOH channel
	FPix_BpI_D1_PRT2    FPix_BpI_D1_PNL4 A     1
	FPix_BpI_D1_PRT2    FPix_BpI_D1_PNL5 A     2
	</pre>
	For each portcard the modules are listed and the corresponding
	AOH channel is listed.  The TBM channel, ``<b><tt>A</tt></b>" or ``<b><tt>B</tt></b>", is
	specified after the module name.  (If no TBM channel is specified, it
	defaults to ``<b><tt>A</tt></b>".)

	The AOH channel numbering begins from 1.  On each forward pixel port card, there is one AOH with 6 channels, so the numbering goes from 1 to 6.  On barrel supply boards, there are 4 AOHs, each with 6 channels.  The numbering goes from 1 to 24.  The first AOH contains channels 1-6, the second contains channels 7-12, etc.


      \section page3Sect14 PixelPortCardConfig

	This class holds the settings that are used on
	each portcard.

	The format of the portcard configuration file is
	<pre>
	Name: FPix_BpI_D1_PRT1
	TKFECID: tkfec1
	ringAddress: 0x8
	ccuAddress: 0x7d
	channelAddress: 0x10
	i2cSpeed: 0x64
	Delay25_GCR: 0x0
	Delay25_SCL: 0x60
	Delay25_TRG: 0x68
	Delay25_SDA: 0x5c
	Delay25_RCL: 0x60
	Delay25_RDA: 0x60
	AOH_Bias1: 0x19
	AOH_Bias2: 0x1f
	AOH_Bias3: 0x1f
	AOH_Bias4: 0x1f
	AOH_Bias5: 0x1f
	AOH_Bias6: 0x1f
	AOH_Gain1: 0x2
	AOH_Gain2: 0x0
	AOH_Gain3: 0x0
	AOH_Gain4: 0x0
	AOH_Gain5: 0x0
	AOH_Gain6: 0x0
	</pre>
	In the barrel, there are 4 AOH devices, denoted <b><tt>AOH1</tt></b>, <b><tt>AOH2</tt></b>, <b><tt>AOH3</tt></b>, and <b><tt>AOH4</tt></b>.  
	Each of these 4 devices has 6 channels, each with its own bias and gain.  
	For example, <b><tt>AOH1_Bias1</tt></b>, <b><tt>AOH1_Gain5</tt></b>, <b><tt>AOH2_Bias3</tt></b>, <b><tt>AOH4_Gain6</tt></b>.

	In addition, values may be specified for the settings <b><tt>PLL_CTR1</tt></b>, <b><tt>PLL_CTR2</tt></b>, <b><tt>PLL_CTR3</tt></b>, 
	<b><tt>PLL_CTR4</tt></b>, 
	<b><tt>DOH_Ch0Bias_CLK</tt></b>, <b><tt>DOH_Ch1Bias_Data</tt></b>, and <b><tt>DOH_Gain_SEU</tt></b>.

	Prior to loading the settings in the file, an initialization sequence is sent to the port card:
	<pre>
	PLL_CTR1: 0x8
	PLL_CTR1: 0x0
	PLL_CTR2: 0x20
	PLL_CTR4: 0x15
	PLL_CTR1: 0x1
	</pre>
	Then the device settings in the file (all lines after <b><tt>i2cSpeed: 0x64</tt></b>) are loaded in the order given.

      \section page3Sect15 PixelDelay25Calibration

	This class specifies the parameters used in the delay 25 scan
	for the delay settings of return data and send data. An
	example of the configuration files used for this calibration
	is given below

	<pre>
	Mode:
	Delay25
	Portcards:
	FPix_BmI_D1_PRT2
	AllModules:
	0
	OrigSDa:
	64
	OrigRDa:
	64
	Range:
	64
	GridSize:
	8
	Tests:
	10
	StableRange:
	6
	StableShape:
	2
	</pre>

    __________________________________________________________________________________
    \page page4 4- Usage of configuration data in xdaq applications

	This section contains a brief description of how the configuration data 
	objects are used. 

	First we look at the PixelSupervisor. RCMS, via the PixelFunctionManager,
	will pass a string for a configuration alias to the PixelSupervisor
	during the configure transition. The PixelSupervisor gets the configuration
	alias and looks up the corresponding configuration key:
	<pre>
	  std::string alias=parametersReceived[0].value_;
	  unsigned int globalKey=PixelConfigDB::getAliases_map().find(alias)->second;
	  theGlobalKey_=new PixelConfigKey(globalKey);
	</pre>
	<i>This code should be fixed so that it catches if the alias does
	not exist. This can be an assert, as the choices for the alias are
	listed from the same map and not being able to find it is an internal
	error.</i>

	Having obtained the configuration key this is what is used to extract
	configuration data. For example the PixelSupervisor extracts some
	objects:
	<pre>
	  PixelConfigDB::get(theCalibObject_, "pixel/calib/", *theGlobalKey_);
	  PixelConfigDB::get(theDetectorConfiguration_, "pixel/detconfig/", *theGlobalKey_);
	</pre>
	The get method returns a pointer that the PixelSupervisor is responsible
	for deleting.

	When the PixelSupervisor asks the other supervisors to configure it does
	this by passing the configuration key, not the alias, to them. This
	guarantees that the configuration used by the different supervisors 
	is consistent. We only need to retain the configuration key as a record
	of how the detector was configured.

	Inside the PixelFECSupervisor in the configuration method we have code 
	like

	<pre>
	  PixelConfigDB::get(theNameTranslation_, "pixel/nametranslation/", *theGlobalKey_);
	  assert(theNameTranslation_!=0);

	  PixelConfigDB::get(theDetectorConfiguration_, "pixel/detconfig/", *theGlobalKey_);
	  assert(theDetectorConfiguration_!=0);

	  PixelConfigDB::get(theFECConfiguration_, "pixel/fecconfig/", *theGlobalKey_);
	  assert(theFECConfiguration_!=0);
	  assert(theFECConfiguration_->getNFECBoards()==1); //FIXME

	  PixelConfigDB::get(theCalibObject_, "pixel/calib/", *theGlobalKey_);
	  calibStateCounter_=0;

	  // Loop over all modules in the Detector Configuration and instantiate FECInterfaces required in this crate.
	  // Download TBM, DAC, Masks and Trim settings into hardware.
	  std::vector <PixelModuleName>::iterator module_name = theDetectorConfiguration_->getModuleList().begin();
	  for (;module_name!=theDetectorConfiguration_->getModuleList().end();++module_name)
	 {
	   diagService_->reportError("Congiguring module=" + module_name->modulename(),DIAGDEBUG);
	   const PixelHdwAddress* module_hdwaddress=theNameTranslation_->getHdwAddress(*module_name);

	  unsigned int fecnumber=module_hdwaddress->fecnumber();
	  unsigned int feccrate=theFECConfiguration_->crateFromFECNumber(fecnumber);
	  unsigned int fecVMEBaseAddress=theFECConfiguration_->VMEBaseAddressFromFECNumber(fecnumber);

	  if (feccrate==crate_){
	    PixelMaskBase *tempMask=0;
	    PixelTrimBase *tempTrims=0;
	    PixelDACSettings *tempDACs=0;
	    PixelTBMSettings *tempTBMs=0;
	    std::string modulePath=(module_name->modulename());

	    PixelFECInterface* tempFECInterface=new PixelFECInterface(fecVMEBaseAddress, aBHandle);
	    assert(tempFECInterface!=0);
	    tempFECInterface->setssid(4);

	    PixelConfigDB::get(tempMask, "pixel/mask/"+modulePath, *theGlobalKey_);
	    assert(tempMask!=0);
	    theMasks_.insert(make_pair(*module_name, tempMask));

	    PixelConfigDB::get(tempTrims, "pixel/trim/"+modulePath, *theGlobalKey_);
	    assert(tempTrims!=0);
	    theTrims_.insert(make_pair(*module_name, tempTrims));

	    PixelConfigDB::get(tempDACs, "pixel/dac/"+modulePath, *theGlobalKey_);
	    assert(tempDACs!=0);
	    theDACs_.insert(make_pair(*module_name, tempDACs));

	    PixelConfigDB::get(tempTBMs, "pixel/tbm/"+modulePath, *theGlobalKey_);
	    assert(tempTBMs!=0);
	    theTBMs_.insert(make_pair(*module_name, tempTBMs));

	    tempDACs->generateConfiguration(tempFECInterface, theNameTranslation_);
	    tempTBMs->generateConfiguration(tempFECInterface, theNameTranslation_);
	    tempTrims->generateConfiguration(tempFECInterface, theNameTranslation_, *tempMask);

	    FECInterface[fecVMEBaseAddress]=tempFECInterface;
	  }
	 }
	</pre>

	Similar extractions of the configuration data is used by other
	supervisors. The supervisors cache the data received. The data
	is cleared in the halt transition.

      \section page4Sect1 Event builder configurations

	We do not want to build complete events on one node; 
	rather we want to make sure that the event fractions
	from each FED is always shipped to the same filter unit.

	To accomplish this the network fabric of the event 
	builder will need to be reconfigured for each pixel
	calibration run. Note that this is likely to be done
	between each LHC fill. (This does not mean that we
	will determine all constants at this rate, but that
	we will want to monitor quantities such as address
	levels frequently.)

	Freya Blekman has developed the algorithms that analyze 
	the pixel raw data for the purpose of doing gain calibrations,
	pixel alive, and S-curves. Initially this work is 
	done using data recorded in plain files. To progress
	towards the final goal we should first try to run this
	with a filter unit that is fed data from a source
	that reads files. This will allow us to test and develop
	the application in the form it will run in the HLT. The
	second step is to actually run this with data produced 
	from a FED. This can be either real data of playback 
	generated in a DAQ test stand. We have discussed this 
	with Franz Meier. Freya will follow up on this in
	August and September.

	One important question to settle here is if we can generate
	the triggers we need for this using our LTC. 

	We should also test and deploy code so that we can take 
	data using local DAQ (VME) and send it out to an event builder.
	Jim Hunt wrote some of this code. This has not been used
	recently, but we need to deploy this.

      \section page4Sect2 Calibrations

	The two main purposes of the online software are the
	configuration for data taking and the online calibrations
	that are performed between runs for the calibration of
	the detector. There is a large number of different calibration
	tasks that needs to be performed. This section describes
	the algorithms implemented to carry out these calibrations.

	The order of the calibrations described below is the order
	that we nominally run the calibrations in when testing out
	the detector. Some modifications to the order is possible.

      \subsection page4Sect2Sub1 AOH and FED channel mapping test

	The AOH and FED channel mapping test is not really a calibration, but rather a test to 
	see whether the connections between AOH channels and FED channels in the configuration are correct. 
	The idea is to change the AOH bias for a single channel, and look to see whether the black level 
	on the corresponding FED channel changes.  (FED automatic baseline correction must be turned off.)  
	This process is repeated for each channel.  Those for which the black level changes are correctly 
	connected; those for which there is no change are not connected correctly or have a mistake in the 
	configuration files.

      \subsubsection page4Sect2Sub1Sub1 Mapping test steps

	The steps of this calibration are listed in order below.
	<ol>
	<li> Set the FED channels to the 2V peak-to-peak range in order to provide
	     maximum dynamic range for the AOH bias scan.
	<li> Turn off the FED automatic baseline correction.
	<li> Set all FED optical receiver input offsets to 8, and channel offsets to 255.  
	     These settings tend to put the signal in a range where the black level will not be stuck at the 
	     top or bottom of the range as AOH bias is varied.  (Maybe this step should be removed, and the 
	     default values should be used instead.)
	<li> Issue <b><tt>ClrCal</tt></b> to all ROCs, and disable hits with the control
	     register on all ROCs, to ensure that no hits are output.
	<li> Issue <b><tt>LRES</tt></b> and <b><tt>CLRES</tt></b> commands to all FEDs to clear the
	     transparent data.  This ensures that no stale data is sitting in the buffer.
	<li> On the first channel, loop over AOH bias values.  On each trigger, inspect the transparent buffer 
	     and look for the start of the signal.  Record the black levels in the time slots preceeding the 
	     start of the signal.  Keep track of the mean black level and the standard deviation for each AOH bias value.  
	     A plot of this scan is written to a ROOT file.
	<li> Inspect the scan of black level vs.~AOH bias.  If the black level varies as AOH bias changes, 
	     this channel is properly connected.  If the black level is constant, this channel is flagged as improperly connected.  
	     (Quantitatively, the \\chi^2 of the scan data is evaluated for the hypothesis of a flat line.  
	     If \\chi^2d.o.f. > 100, the scan data is considered to vary; otherwise it is considered constant.)  
	     One exception is if the scan is constant at the top or bottom of the range (1023 or 0).  
	     In this case the signal is out of range, and so the connectivity test is inconclusive.
	<li> Set AOH bias back to the default value (from the configuration).  This ensures that channels are not 
	     falsely flagged as being stuck at the top of the range.  If, say, two FED channels were swapped in the configuration, 
	     the first one scanned would show up as incorrectly connected.  With the AOH left at the highest scan point, 
	     when the FED channel that is actually connected to that AOH is checked later, the black level will appear 
	     to be stuck at the top of the range.  Setting that AOH back to its default value should put the black level 
	     on that channel back into the middle of the range.
	<li> Repeat the AOH bias scan for each channel in the configuration.
	<li> Print a summary to the screen.  Thus summary gives the number of
	     channels which are properly connected, improperly connected, or for which the test was inconclusive.  
	     Improperly connected and inconclusive channels are then listed.
	</ol>

      \subsubsection page4Sect2Sub1Sub2 Parameters
	
	A number of parameters in <b><tt>calib.dat</tt></b> may be used to control the
	test.

	Only two ``standard" parameters are used.  The ``<b><tt>Repeat:</tt></b>" parameter
	determines the number of triggers at each AOH bias scan point.  The
	channel list is used to determine which channels are calibrated.  Note that
	the rows, columns, and DAC scan settings in <b><tt>calib.dat</tt></b> are completely
	ignored.

	Some optional parameters may also be set.  All have default values which
	will be used if the parameter is not set.  These parameters, their defaults,
	and their functionality are given in Table~AOHAndFEDChannelMappingTestParameters.

	\\caption{Optional parameters for AOH and FED channel mapping test.}
	\\label{tab:AOHAndFEDChannelMappingTestParameters}
        <center>
	 <table>
  	  <tr>
	   <td> Parameter 	  </td><td> Default </td><td> Description		     		       </td>
	  </tr>
	  <tr>
	   <td> ScanMin   	  </td><td>   0     </td><td> Low end of AOH bias scan range 		       </td>
	  </tr>
	  <tr>
	   <td> ScanMax           </td><td>  50     </td><td> High end of AOH bias scan range 		       </td>
	  </tr>
	  <tr>
	   <td> ScanStepSize      </td><td>   5     </td><td> Step size for AOH bias scan 		       </td>
	  </tr>
	  <tr>
	   <td> printFEDRawData   </td><td>  no     </td><td> Whether to print decoded transparent buffer      </td>
	  </tr>
	  <tr>
	   <td> printScan         </td><td>  no     </td><td> Whether to print the AOH bias scan to the screen </td>
	  </tr>
         </table>
	</center>

      \subsubsection page4Sect2Sub1Sub3 FED phase and delay scan

	The FED has a delay (0 to 15) that goes in steps of 25/16 ns.
	In addition to the delay there is a phase that controls when
	the data is latched. Certain combinations of the delay and
	phase are invalid and result in garbage ADC values. 

	In this calibration the 32 values of the phase and delay 
	are scanned. For each setting of the phase and delay a
	fixed number of events (typically around 10) 
	is read out in transparent mode. 

	A detailed description of this algorithm, is presented in
	Appendix~phaseanddelay.

     \subsubsection page4Sect2Sub1Sub4 Output

	The FED phase and delay calibration produces new
	fed_params.dat files that are updated with the new
	FED settings for the phase and delay. The files
	should otherwise be identical to the input files
	specified in the configuration. In addition to the
	fed_params.dat files the are a number of pdf file
	files generated. For each channel you get four
	output files:
	<pre>
	PhaseAndDelayRaw_37_1.pdf
	PhaseAndDelayPurged_37_1.pdf
	PhaseAndDelayOrdered_37_1.pdf
	PhaseAndDelayFinal_37_1.pdf
	</pre>
	Where the numbers in the file name represent the fed id and
	the fed channel. Appendix~phaseanddelay gives
	examples of these plots.

     \subsubsection page4Sect2Sub1Sub5 Example configuration

	An example of a configuration file to run the 
	phase and delay scan is given below.

	<pre>
	Mode: ClockPhaseCalibration
	Rows:
	Cols:
	Vcal:
	100 100 5
	Repeat:
	10
	ToCalibrate:
	all
	</pre>

	As described in Appendix~phaseanddelay one can
	change the algorithm used to find the best phase and delay
	using

	<pre>
	Parameters:
	oldMode Yes
	</pre>


     \subsection page4Sect2Sub2 Delay25 settings for send data and return data

	This calibration scans the delay for the send data and
	return data. For each set of values commands are sent to
	the TBM and the return status in the (pixel) FEC is checked.
	This calibration uses the PixelFECInterface::testDelay25 method
	that sends 4 different types of commands. This algorithm
	focuses combines the results from the 4 different types
	of commands and only if all 4 succeeded will you get 100%
	efficiency.

	Note that this algorithm does not check that the TBM or 
	ROC actually received the
	command, it just checks the return status.

     \subsection page4Sect2Sub2Sub1 Output

	The main output from this calibration is new delay settings
	that stored in the portcard files. The only changes made
	to the port card settings are for the send data and 
	return data delays.

	In addition to generating the new portcard files with
	delay settings the scans are saved in the files:

	<pre>
	graph_FPix_BmO_D1_PRT3_FPix_BmO_D1_BLD8_PNL1.dat
	good_FPix_BmO_D1_PRT3_FPix_BmO_D1_BLD8_PNL1.dat
	</pre>

	The 'graph_*.dat' files contains the efficiency
	at each of the scan points. The 'good_*.dat' files
	contains the list of points that had 100% efficiency.
	To view the output you can run the root macro <tt><b>delay25.c</b></tt>
	to generate plots. An example plot is shown in
	Fig. Delay25Scan.

	 \\\includegraphics[width=0.8\\textwidth]{graph_FPix_BmO_D2_PRT3_FPix_BmO_D2_BLD8_PNL1.pdf}
	This plot shows efficiency as a function of RDa and SDa. The blue
	dots indicates areas with 100\\% transmission efficiency. The black
	dots indicated partial efficiency, larger dots have higher efficiency.
	The red square indicates the point chosen by the algorithm.





     \subsection page4Sect2Sub2Sub2 Delay25 trigger setting

	<i>Not implemented.</i> Should also scan the trigger delay to 
	make sure that the triggers are received correctly. Can we
	just scan the delay setting and look at the corresponding FED 
	channel to make sure that the trigger arrived? I.e. that we
	saw data in the FED? You would need to do this before you run
	the phase and delay scan of the FED?


     \subsection page4Sect2Sub3 AOH bias settings

     \subsection page4Sect2Sub3Sub1 Introduction and discussion

	The AOH bias is a setting on the port card which controls the
	amount of light sent to the FED.  There is one AOH bias setting
	per FED channel.  As AOH bias increases, more light is sent,
	and the ADC values on the FED increase.  At low values of AOH
	bias, both black and ultrablack do not change with AOH bias,
	and there is no separation between black and ultrablack levels.
	At some threshold, the black level begins to increase
	approximately linearly.  At a higher threshold, the ultrablack
	level also starts to increase linearly with approximately the
	same slope.  This behavior is illustrated in
	Fig.~AOHBiasScan.

	
	
	 \\includegraphics[angle=90,width=0.99\\textwidth]{AOHBiasScan.pdf}
	
	\\caption{Black and ultrablack levels as a function of AOH bias.}
	\\label{fig:AOHBiasScan}
	

	Note that the maximum black-ultrablack separation depends on how
	the TBM DACs are set.  At low DAC settings, the TBM outputs a
	signal with relatively low separation; as these settings increase,
	the separation also increases.  In the AOH bias scan, the black
	level is independent of the TBM settings.  However, the linear
	rise of the ultrablack level begins at a later point for higher
	TBM settings, and hence the black-ultrablack difference saturates
	at a higher AOH bias value when the TBM DAC settings are higher.

	The goal of the AOH bias calibration is to determine an AOH bias
	setting for each channel that is just high enough to saturate the
	black-ultrablack difference.  The calibration measures this
	difference, using black and ultrablack levels from the TBM header
	and trailer, as a function of AOH bias.  It is important, though,
	that during the scan the TBM DACs are set at least as high as they
	will be set in later calibrations and physics runs.  Otherwise, the
	AOH bias value determined from the saturation point will be too low.
	TBM settings above those used in this scan will not increase the
	B-UB separation because the AOH cannot provide more separation.

	It is also important that the AOH bias not be too high; otherwise
	the FED offsets could not bring the signal into the dynamic range
	of the FED.

	The last part of the AOH bias calibration is to do a coarse baseline
	adjustment.  The FED channel offsets are set to the center of the
	range (127), and then the FED optical receiver offsets and AOH bias settings
	are adjusted to bring all FED baselines into a wide target range.  AOH bias
	is not decreased below the saturation value unless it is absolutely necessary.
	The end result is a configuration of AOH bias and FED offset values that puts
	all FED baselines near the center of the dynamic range, with AOH bias values
	that allow for a large B-UB separation.  After the AOH bias calibration, the
	FED baseline calibration should be run to perform fine adjustments of the
	baseline (using the freedom to move each channel offset).

     \subsection page4Sect2Sub3Sub2 AOH bias calibration steps

	This calibration involves many distinct steps.  They are listed in order
	below.  Each step is performed on each channel being calibrated.
	<ol>
	<li> Set the FED channels to the 2V peak-to-peak range in order to provide
	maximum dynamic range for the AOH bias scan.
	<li> Turn off the FED automatic baseline correction.
	<li> Issue <b><tt>ClrCal</tt></b> to all ROCs, and disable hits with the control
	register on all ROCs, to ensure that no hits are output.
	<li> Set all TBM DACs to high values.  These values may be specified as
	parameters in <b><tt>calib.dat</tt></b>.
	<li> Set all FED optical receiver input offsets to the highest useful value
	(the setting that minimizes the FED ADC values, without impairing the B-UB
	separation).  This value is configurable, and it defaults to 8 (on a scale
	from 0 to 15).  Also, all channel offsets are set their maximum value, 255.
	
	<li> Issue <b><tt>LRES</tt></b> and <b><tt>CLRES</tt></b> commands to all FEDs to clear the
	transparent data.  This ensures that no stale data is sitting in the buffer.
	<li> Loop over AOH bias values.  Attempt to decode the transparent
	buffer on each trigger, assuming the correct number of ROCs and no hits.
	That is, find the TBM header, and verify that the TBM trailer is in the
	right place.  When decoding is successful, record the start slot of
	the TBM header and trailer.  On each channel, this slot should be the same for
	all triggers.  The reason for this step is to find the time slots for later
	use in reading out TBM B and UB levels, even at low AOH bias settings where
	full decoding would fail.  If no reliable time slots are found on a channel,
	this channel is considered failed, and it is ignored in the rest of the
	routine.
	<li> Now scan over AOH bias again, this time to record the TBM B and UB
	levels at each setting, using the time slots recorded in the previous step.
	This scan will be done 12 times -- once for each channel on a FED optical
	receiver.  (All FED channels 1, 13, and 25 will be scanned at once; then all
	channels 2, 14, and 26; etc.  If no FED channel in the configuration has one
	of the three numbers, the scan for those numbers is skipped.)  During the
	scan, if the signal goes out of range high or low, the FED optical receiver
	input offset and/or the FED channel offset is adjusted to bring it back into
	range, if possible.  (This is the reason for scanning only one channel per
	receiver at a time.)  Since only the B-UB difference is of interest, coherent
	shifts in B and UB do not matter.  The receiver input offset may not exceed
	the maximum value described in step \\\ref{item:FEDReceiverOffset} (defaults
	to 8).  Prior to each scan, step \\\ref{item:FEDReceiverOffset} is repeated.
	<li> Output plots of the TBM black and ultrablack, and the difference, as a
	function of AOH bias, to a ROOT file.  Figure~\\\ref{fig:AOHBiasScan} is an example of the
	plots produced.  Find the AOH bias value at which the B-UB difference
	saturates (defined as a reduction in the slope to less than 20% of its
	maximum value).  Set each AOH to its saturation value.
	<li> Set FED channels back to the 1V peak-to-peak range, for those channels
	which were originally set at 1V in the FED configuration file.  This is done
	so that the coarse baseline adjustment will be done with the range that will
	be used for future data-taking.
	<li> Set FED optical receiver input offsets to 0 (lowest value,
	corresponding to highest FED ADC values), and all channel offsets to 127
	(middle of the range).  The channel offset will be left at 127 for the rest
	of the routine.
	<li> Measure black levels on all channels.  On each FED optical receiver,
	if any channel has a black level above the target range, increase that
	receiver's offset by one.  If not, do nothing.  Repeat this until all
	channels have black levels in or below the target range, or have a receiver
	offset equal to the maximum value described in
	step \\ref{item:FEDReceiverOffset} (defaults to 8).  The idea here is to
	ensure that no AOH bias value will have to be decreased to place the black
	level in the target range (unless this is absolutely necessary because the
	receiver offset cannot be increased further).
	<li> Again measure the black levels on all channels.  If a channel's black
	level is within the target range, that channel is done.  If it is above or
	below the target range, decrease or increase AOH bias.  Repeat this until all
	channels are within range.  (Or, if two adjacent AOH bias values produce
	black levels that straddle the target range, chose the one that is closer to
	the target.)  AOH bias should not have to decrease unless the FED receiver
	input offset was at maximum.  If it does decrease, a warning is generated in
	the summary at the end of the calibration.
	<li> Turn FED automatic baseline correction back on.
	<li> Write new config files for all port cards and FEDs with at least one
	successfully calibrated channel.
	<li> Print a summary to the screen.  Thus summary gives the number of
	successful and failed channels, statistics on the new settings for successful
	channels, descriptions of the errors on unsuccessful channels, and warnings
	for channels on which the final AOH bias setting is below the saturation
	point.
	</ol>

     \subsection page4Sect2Sub3Sub3 Parameters

	A number of parameters in <b><tt>calib.dat</tt></b> may be used to control the
	calibration.

	Only two ``standard" parameters are used.  The ``<b><tt>Repeat:</tt></b>" parameter
	determines the number of triggers in each step (at each AOH bias scan point
	and when measuring black levels in the coarse baseline adjustment).  The
	channel list is used to determine which channels are calibrated.  Note that
	the rows, columns, and DAC scan settings in <b><tt>calib.dat</tt></b> are completely
	ignored.

	Many other optional parameters may be set.  All have default values which
	will be used if the parameter is not set.  These parameters, their defaults,
	and their functionality are given in Table~\\ref{tab:AOHBiasParameters}.

	\\caption{Optional parameters for AOH bias calibration.}
	\\label{tab:AOHBiasParameters}
        <center>
	 <table>
	  <tr>
	   <td> Parameter		  <td></td> Default <td></td> Description				   </td>
	  </tr>
	  <tr>
	   <td> ScanMin 		  <td></td>   0     <td></td> Low end of AOH bias scan range		   </td>
	  </tr>
	  <tr>
	   <td> ScanMax 		  <td></td>  50     <td></td> High end of AOH bias scan range		   </td>
	  </tr>
	  <tr>
	   <td> ScanStepSize		  <td></td>   1     <td></td> Step size for AOH bias scan		   </td>
	  </tr>
	  <tr>
	   <td> TargetBMin		  <td></td> 412     <td></td> Allowed range for the coarse baseline	   </td>
	  </tr>
	  <tr>
	   <td> TargetBMax		  <td></td> 612     <td></td> adjustment at the end of this calibration    </td>
	  </tr>
	  <tr>
	   <td> MaxFEDReceiverInputOffset <td></td>   8     <td></td> Largest allowed value of the FED receiver    </td>
	  </tr>
	  <tr>
	   <td> 			  <td></td>	    <td></td> input offset, which can range from 0 to 15   </td>
	  </tr>
	  <tr>
	   <td> SetAnalogInputBias	  <td></td> 200     <td></td> TBM settings to use			   </td>
	  </tr>
	  <tr>
	   <td> SetAnalogOutputBias	  <td></td> 120     <td></td> for all channels --			   </td>
	  </tr>
	  <tr>
	   <td> SetAnalogOutputGain	  <td></td> 200     <td></td> all 3 should be set high  		   </td>
	  </tr>
	  <tr>
	   <td> printFEDRawData 	  <td></td>  no     <td></td> Whether to print decoded transparent buffer  </td>
	  </tr>
	  <tr>
	   <td> printFEDOffsetAdjustments <td></td>  no     <td></td> Whether to print when the FED offsets change </td>
	  </tr>
	  <tr>
	   <td> printAOHBiasAdjustments   <td></td>  no     <td></td> Whether to print a message when the AOHBias  </td>
	  </tr>
	  <tr>
	   <td> 			  <td></td>	    <td></td> is changed during the baseline adjustment    </td>
	  </tr>
         </table>
	</center>

	\\subsection{FED baseline calibration}

	This calibration adjusts the input offset and channel
	offsets of the optical receivers in the FED such that the
	black level is adjusted to be near a given target value,
	normally 512, which is the midpoint of the 
	dynamic range of the ADC. During this calibration the 
	baseline correction in the FED is turned off.

	Besides determining the input offset and the channel
	offsets the algorithm determines address levels for the
	black and ultra-black levels.

	<i>Souvik: add more details, example plots, configuration
        	     examples.</i>

	\\subsection{TBM UB calibration}

	\\subsubsection{Introduction and discussion}

	With the black level set at 512 by the baseline calibration and automatic
	baseline correction, the next step is to set the ultrablack levels
	appropriately.  We first adjust DACs on the TBM to set the TBM header and
	trailer ultrablack to an appropriate value. (Experience
	from forward testing suggests that a value of 120 to 150 is good.)

	There are three DAC settings on the TBM, all of which affect the ultrablack
	level.  Higher values of these DACs correspond to lower ultrablack (and
	greater B-UB separation).  Figure~\\ref{fig:tbm-anal-dacs} shows how these
	DACs affect the output of the TBM.  The <b><tt>AnalogOutputGain</tt></b> setting
	alters the levels of the TBM header and trailer, but not the signals from
	the ROCs.  The <b><tt>AnalogInputBias</tt></b> setting affects both ROC and TBM
	signals, but it changes ROC signals more than TBM signals.  The
	<b><tt>AnalogOutputBias</tt></b> setting affects ROC and TBM signals equally.

	
	
	 \\includegraphics[width=0.99\\textwidth]{tbm-anal-dacs.png}
	
	\\caption{Diagram illustrating how the TBM DACs affect the output of the TBM.
	AnalogInputBias is referred to as Input AMP Bias (blue arrows),
	AnalogOutputBias is referred to as Output AMP Bias (red arrows),
	and AnalogOutputGain is referred to as TBM Gain (green arrows).}
	\\label{fig:tbm-anal-dacs}
	

	The TBM UB level may be adjusted by any of these three DAC settings.  In
	practice, the TBM UB calibration routine fixes two of them and scans the
	third, searching for a value that puts the TBM UB at the target level.
	(This level defaults to 135, and may be changed by the user.)  By default
	the <b><tt>AnalogOutputGain</tt></b> setting, which affects only the TBM header and
	trailer, is scanned while the other two DACs are fixed.  The user may
	choose, however, to scan one of the other DACs instead.

	Dual TBMs are a special case.  The two channels on a dual TBM share the
	same DAC settings, so they cannot be adjusted independently.  Therefore the
	TBM settings cannot be adjusted to simultaneously put both channels' UB at
	the target level.  For dual TBMs, we set the DACs so that one channel is at
	the target UB level, and the other is below.

	\\subsubsection{TBM UB calibration steps}

	The calibration consists of the following steps:
	<ol>
	<li> Issue <b><tt>ClrCal</tt></b> to all ROCs, and disable hits with the control
	register on all ROCs, to ensure that no hits are output.
	<li> Issue <b><tt>LRES</tt></b>  and <b><tt>CLRES</tt></b> commands to all FEDs to clear the
	transparent data.  This ensures that no stale data is sitting in the buffer.
	<li> If the user has specified particular values for the two DACs which will
	not be scanned, set all TBMs with those values.
	<li> Scan over values of the desired DAC.  Attempt to decode the transparent
	buffer on each trigger, assuming the correct number of ROCs and no hits.
	That is, find the TBM header, and verify that the TBM trailer is in the
	right place.  If decoding is successful, record the
	UB values in the TBM header and trailer (5 values per trigger, 3 from the
	header and 2 from the trailer).  If decoding is unsuccessful, ignore that
	trigger, and don't record anything.  For each TBM, a plot of this scan is
	output to a ROOT file.
	<li> Analyze the recorded scan data on each FED channel, looking for the
	point where the measured UB crosses the target level.  When the crossing is
	found, interpolate between the nearest scan points for the best DAC setting.
	If no crossing is detected, or multiple crossings are detected, the channel
	is considered failed, and no new DAC setting will be written out.  (If either
	channel on a dual TBM fails, no new DAC setting will be written out for that
	module.)
	<li> On single TBMs, the new DAC value is the value at this crossing point.
	On dual TBMs, the new DAC value is the higher of the two values found on the
	two FED channels for that TBM; this ensures that both UB levels will be at or
	below the target.
	<li> Write out new TBM configuration files for the successfully-calibrated
	modules with the new DAC settings.  If one or both of the other two DAC
	settings were modified by the user, the output files will contain these new
	values, too.
	<li> Print out a summary.
	</ol>

	\\subsubsection{Parameters}
	A number of parameters in <b><tt>calib.dat</tt></b> may be used to control the
	calibration.

	Only two ``standard" parameters are used.  The ``<b><tt>Repeat:</tt></b>" parameter
	determines the number of triggers in each step of the scan.  The module list
	is used to determine which channels are calibrated.  Note that the rows,
	columns, and DAC scan settings in <b><tt>calib.dat</tt></b> are completely ignored.

	Many other optional parameters may be set.  All have default values which
	will be used if the parameter is not set.  These parameters, their defaults,
	and their functionality are given in Table~\\ref{tab:TBMUBParameters}.

	\\caption{Optional parameters for TBM UB calibration.}
	\\label{tab:TBMUBParameters}
        <center>
	 <table>
	  <tr>
	   <td> Parameter             </td><td> Default            </td><td> Description                        	   </td>
          </tr>
	  <tr>
	   <td> DACToScan	      </td><td> AnalogOutputGain   </td><td> Which of the three TBM DACs to scan	   </td>
          </tr>
	  <tr>
	   <td> ScanMin 	      </td><td> [depends on DAC]   </td><td> Low end of DAC scan range  		   </td>
          </tr>
	  <tr>
	   <td> ScanMax 	      </td><td> [depends on DAC]   </td><td> High end of DAC scan range 		   </td>
          </tr>
	  <tr>
	   <td> ScanStepSize	      </td><td> 5		   </td><td> Step size for DAC scan     		   </td>
          </tr>
	  <tr>
	   <td> SetAnalogInputBias    </td><td> [empty] 	   </td><td> If not set, leave AnalogInputBias unchanged.  </td>
          </tr>
	  <tr>
	   <td>  		      </td><td> 		   </td><td> Otherwise, set it to the specified value and  </td>
          </tr>
	  <tr>
	   <td>  		      </td><td> 		   </td><td> change in the output configuration file.      </td>
          </tr>
	  <tr>
	   <td> SetAnalogOutputBias   </td><td> [empty] 	   </td><td> If not set, leave AnalogOutputBias unchanged. </td>
          </tr>
	  <tr>
	   <td>  		      </td><td> 		   </td><td> Otherwise, set it to the specified value and  </td>
          </tr>
	  <tr>
	   <td>  		      </td><td> 		   </td><td> change in the output configuration file.      </td>
          </tr>
	  <tr>
	   <td> SetAnalogOutputGain   </td><td> [empty] 	   </td><td> If not set, leave AnalogOutputGain unchanged. </td>
          </tr>
	  <tr>
	   <td>  		      </td><td> 		   </td><td> Otherwise, set it to the specified value and  </td>
          </tr>
	  <tr>
	   <td>  		      </td><td> 		   </td><td> change in the output configuration file.      </td>
          </tr>
	  <tr>
	   <td> TargetUB	      </td><td> 135		   </td><td> Desired TBM UB level                   	   </td>
          </tr>
	  <tr>
	   <td> DualTBMMaxSettingDiff </td><td> 30		   </td><td> Maximum allowed difference between the 	   </td>
          </tr>
	  <tr>
	   <td>  		      </td><td> 		   </td><td> final DAC settings on the two channels 	   </td>
          </tr>
	  <tr>
	   <td>  		      </td><td> 		   </td><td> of a dual TBM                          	   </td>
          </tr>
	  <tr>
	   <td> printFEDRawData       </td><td> no		   </td><td> Whether to print decoded transparent buffer   </td>
          </tr>
	  <tr>
	   <td> printScan	      </td><td> no		   </td><td> Whether to print TBM UB levels 		   </td>
          </tr>
	  <tr>
           <td>                       </td><td> 		   </td><td> for each DAC setting           		   </td>
          </tr>
	 </table>
        </center>

	\\subsection{ROC UB equalization calibration}

	\\subsubsection{Introduction and discussion}

	This calibration sets the ultrablack level for each ROC equal to the
	corresponding TBM's ultrablack level.

	There are two DAC settings on the ROC which affect the ultrablack level.
	Higher values of these DACs correspond to lower ultrablack (and greater
	B-UB separation).  <b><tt>VIbias_roc</tt></b> affects UB, address levels, and pulse
	height.  <b><tt>VIbias_DAC</tt></b> affects UB and address levels, but not pulse
	height.  In this routine, <b><tt>VIbias_DAC</tt></b> is scanned while
	<b><tt>VIbias_roc</tt></b> is fixed.

	\\subsubsection{ROC UB equalization calibration steps}

	This calibration is very similar to the TBM UB calibration, except that each
	individual ROC is analyzed.  It consists of the following steps:
	<ol>
	<li> Issue <b><tt>LRES</tt></b> and <b><tt>CLRES</tt></b> commands to all FEDs to clear the
	transparent data.  This ensures that no stale data is sitting in the buffer.
	<li> Scan over values of <b><tt>VIbias_DAC</tt></b>.  (If the calib.dat file
	specified a fixed value of <b><tt>VIbias_roc</tt></b>, this is also set.)  Each time
	after <b><tt>VIbias_DAC</tt></b> is changed, issue <b><tt>ClrCal</tt></b> to all ROCs, and
	disable hits with the control
	register on all ROCs, to ensure that no hits are output (so any hits
	specified in the configuration file are ignored).  Attempt
	to decode the transparent buffer on each trigger, assuming the correct
	number of ROCs and no hits.  That is, find the TBM header, and verify that
	the TBM trailer is in the right place.  If decoding is successful, record
	the UB values in the TBM header and trailer, and for each ROC.  If decoding
	is unsuccessful, ignore that trigger, and don't record anything.  For each
	ROC, a plot of this scan is written to a ROOT file.
	<li> Analyze the recorded scan data on each ROC, looking for the point
	where the measured ROC UB equals the UB level on the corresponding TBM.
	When the ROC UB crosses the TBM UB, interpolate between the nearest scan
	points for the best <b><tt>VIbias_DAC</tt></b> setting.  If no crossing is detected,
	or multiple crossings are detected, the ROC is considered failed, and no new
	<b><tt>VIbias_DAC</tt></b> setting will be written out.
	<li> Write out new ROC configuration files for the successfully-calibrated
	ROCs with the new <b><tt>VIbias_DAC</tt></b> settings.  If <b><tt>VIbias_roc</tt></b> was
	modified by the user, the output files will contain this new value, too.
	<li> Print out a summary.
	</ol>

	\\subsubsection{Parameters}
	A number of parameters in <b><tt>calib.dat</tt></b> may be used to control the
	calibration.

	The various ``standard" parameters are used in this calibration.  The
	``<b><tt>Repeat:</tt></b>" parameter determines the number of triggers in each step
	of the scan.  The ROC list is used to determine which ROCs are calibrated.

	A line like
	<pre>
	Scan: VIbias_DAC 80 200 5
	</pre>
	must be included to specify the scan range (first two numbers) and step
	size (last number).

	Optionally, <b><tt>VIbias_roc</tt></b> may be set with a line like
	<pre>
	Set: VIbias_roc 150
	</pre>

	Any hits specified in <b><tt>Rows:</tt></b> and <b><tt>Columns:</tt></b> will be
	ignored.  (This is done by explicitly clearing them.)  The <b><tt>Rows:</tt></b> and
	<b><tt>Columns:</tt></b> parameters should be empty; otherwise the calibration will work
	but will print a warning message.

	Some optional parameters may also be set.  All have default values which will
	be used if the parameter is not set.  These parameters, their defaults, and
	their functionality are given in Table~\\ref{tab:ROCUBParameters}.

	\\caption{Optional parameters for ROC UB equalization calibration.}
	\\label{tab:ROCUBParameters}
        <center>
	 <table>
  	  <tr>
	   <td> Parameter 	  </td><td> Default </td><td> Description		     		  </td>
	  </tr>
	  <tr>
	   <td> printFEDRawData   </td><td> no      </td><td> Whether to print decoded transparent buffer </td>
	  </tr>
	  <tr>
	  </tr>
	  <tr>
	   <td> printScan	  </td><td> no      </td><td> Whether to print TBM UB levels 		  </td>
	   <td>  		  </td><td>	    </td><td> for each DAC setting           		  </td>
	  </tr>
	 </table>
        </center>


	\\subsection{Settings of CalDelay and VcThreshold}

	These settings are ROC wide and a few pixels are selected and
	a scan over the CalDelay and VcTreshold setting is performed.
	For each setting, triggers are taken and data is looked at
	using FIFO3 to see how many hits we had on each ROC. 
	In order for this algorithm to work the address levels for 
	black and ultra-black has to be set. (There is also an
	implementation that uses the FIFO1, it does not need
	address levels.)

	An example of a scan plot is shown in Fig.~\\ref{fig:caldelvsvcthres}.
	The optimal value is chosen as being 25 DAC settings below
	the 'top of the tornado' for VcThreshold and in the middle
	of the range of CalDelay settings.


	\\subsection{Address level determination}

	The address level determination determines the values used
	by the FED to encode the transparent data. This include 
	address levels for the pixel addresses, TBM header and trailer
	levels, and the black and ultrablack levels.

	Pixels are scanned to make sure that we probe combinations 
	of address levels that could potentially cause problems,
	such as transitions from high to low levels and vice versa.

	Due to limitations in the size of the FIFO1 transparent 
	data size of 512 clocks, we can not even take one hit
	per ROC unless the timing is adjusted such that the 
	start of the pulse train comes relatively early, i.e. in
	the first 20 or so clock cycles. Recall, each ROC, with
	one hit takes 9 clock cycles to read out. Then with 24 ROCs
	in a module we need 216 clock cycles just to read out the 
	hits. Plus about 16 clock cycles to read out the TBM
	headers  


	\\subsubsection{Data volume and time estimate}

	The worst case scenario for an address level 
	calibration is one BPIX crate. We have 16 FED
	cards in one crate, and we can assume that all
	of them are fully populated. This means that we
	have 16x36=576 links. As we read out this
	data in transparent mode we will read 1024 words
	per event (even though the transparent data
	is only 512 bytes long). This means a total of 
	235926 bytes. If we want to go thought all
	pixel we have to read out 4160 times this data
	volume for a total of 9,4 GB. At a speed of
	10 MB/s this will take 940 s. 

	Assuming that we change the transparent data
	FIFO to be 1024 bytes. Then we can easily
	fit 4 hits into each ROC. This then cuts the
	readout time by a factor of 4 as we will need
	exactly 1/4 the number of triggers. This then
	becomes 235 seconds. 

	We can also use different patters that used
	fewer pixel hits. But one has to take care to have all 
	relevant transitions.

	<i>Souvik: Add more details, example plots, and configurations</i>

	\\subsection{Pixel alive, S-curve, and Gain calibration}

	The pixel alive calibration loops over pixel, inject
	charge, for a fixed VCal setting. The data is analyzed
	to produce an efficiency map that displays the efficiency
	for each pixel on a plaquette. 

	The S-curve and gain calibrations are variations of the 
	pixel alive test were we in addition loop over the VCal 
	setting for each pixel. For the S-curve the data is
	analyzed to produce an efficiency as a function of the
	VCal setting while for the gain calibration we 
	look at the charge (ADC value) as function of the VCal.

	All of these calibration as configured using a <tt><b>PixelCalib</b></tt>
	configuration like
	<pre>
	Mode: PixelAlive
	Rows:
	0 | 16 | 32 | 48 | 64 | 
	1 | 17 | 33 | 49 | 65 |
	2 | 18 | 34 | 50 | 66 |
	3 | 19 | 35 | 51 | 67 |
	4 | 20 | 36 | 52 | 68 |
	5 | 21 | 37 | 53 | 69 |
	6 | 22 | 38 | 54 | 70 |
	7 | 23 | 39 | 55 | 71 |
	8 | 24 | 40 | 56 | 72 |
	9 | 25 | 41 | 57 | 73 |
	10 | 26 | 42 | 58 | 74 |
	11 | 27 | 43 | 59 | 75 |
	12 | 28 | 44 | 60 | 76 |
	13 | 29 | 45 | 61 | 77 |
	14 | 30 | 46 | 62 | 78 |
	15 | 31 | 47 | 63 | 79 
	Cols:
	0 | 13 | 26 | 39 | 
	1 | 14 | 27 | 40 |
	2 | 15 | 28 | 41 |
	3 | 16 | 29 | 42 |
	4 | 17 | 30 | 43 |
	5 | 18 | 31 | 44 |
	6 | 19 | 32 | 45 |
	7 | 20 | 33 | 46 |
	8 | 21 | 34 | 47 |
	9 | 22 | 35 | 48 |
	10 | 23 | 36 | 49 |
	11 | 24 | 37 | 50 |
	12 | 25 | 38 | 51 
	Vcal:
	100 100 1
	Repeat:
	10
	Rocs:
	FPix_BmI_D1_BLD1_PNL1_PLQ1_ROC0
	FPix_BmI_D1_BLD1_PNL1_PLQ1_ROC1
	FPix_BmI_D1_BLD1_PNL1_PLQ2_ROC0
	FPix_BmI_D1_BLD1_PNL1_PLQ2_ROC1
	FPix_BmI_D1_BLD1_PNL1_PLQ2_ROC2
	FPix_BmI_D1_BLD1_PNL1_PLQ2_ROC3
	FPix_BmI_D1_BLD1_PNL1_PLQ2_ROC4
	FPix_BmI_D1_BLD1_PNL1_PLQ2_ROC5
	.
	.
	.
	FPix_BmI_D1_BLD3_PNL2_PLQ3_ROC9
	</pre>
	<i>The above configuration is in the old format; should update.</i>


	\\subsubsection{Practical issues}

	If you get a lot of ``Time Out Error'' messages it could
	be because you don't have the right channels enabled on the
	FED. Or more specifically that you have enables channels that
	are not connected.

	\\subsection{Pixel trimbit determination}

	Nothing implemented here. But the algorithm certainly
	needs to be iterative. As the data volume needed to do
	trimbit determination most certainly is very large, one
	need to do an S-curve to determine the threshold,
	it seems obvious that the data has to be acquired using
	global DAQ. This means that it is unlikely that we
	can implement a tight feedback loop. 

	<i>Anders: Discussed a plan with Urs L., can explain
	     this.</i>

	\\subsection{Iana vs. Vana Calibration}

	A calibration called ``Iana'' is implemented to 
	scan Vana and measure the analog current, Iana.
	As the power distribution for the low voltage is 
	done per portcard for the forward pixels (<i>need
	to add how this works for BPix.</i>) this calibration
	works in parallel on a ROC at the time on each
	of the portcards. The current changes we are 
	measuring is of the order 50 mA as you go from
	Vana=0 to Vana=255. The A4603 power modules has
	a resolution of about 7 mA. We perform this 
	measurement when all other ROCs are configured
	to their default values. Hence, we measure the
	current changes on top of a current of several amperes.
	(I performed trials were I lowered Vana on all
	other ROCs to reduce the current, but it does
	not really improve the measurements.)
	Hence, we have to take the data and fit it in order to 
	interpolate between the points. (It takes a 
	long time to do these measurments as one has to
	wait up to 6 seconds before the current measurement
	is stable. This should also be brought up with CAEN.)

	
	
	\\includegraphics[width=0.85\\linewidth]{IanavsVana}
	
	\\caption{This figure shows the measured analog current, Iana,
	vs the Vana setting for a few ROCs. The top left plot shows 
	the Iana measured for one ROC with the A1715 power supply that
	has a better resolution. The black lines indicate the default setting
	(Vana=140) used in the configuration when this data was taken. 
	The red line indicate the setting that gives a analog current of
	25 mA.}
	\\label{fig:IanavsVana}
	


	To analyze the data we fit it to a functional form.
	After some experimentation I came up with the following.
	I divide the range of Vana values into 3 ranges,
	compare Fig.~\\ref{fig:IanavsVana}. In the high range Iana
	is taken to be a constant. In the low range Iana
	is taken to be a constant plus an exponential. 
	In the middle range Iana depends linearly on Vana,
	and the function is required to be continuous. In
	addition the function is required to have a continuous
	derivative as it goes between the low and middle region.
	This function has 5 free parameters that are determined 
	in the fit.

	First the raw data is fit to this form. After doing this
	fit the offset at Vana=0 is subtracted and the data is
	refit and plotted. These are the fits shown in Fig.~\\ref{fig:iana}.

	A black line is used to indicate where the current used for
	the default Vana setting (Vana=140). In red is shown where you should
	set Vana to get an analog current of 25 mA.

	\\subsection{CalDel vs VcThr}
	\\label{sect:caldelvsvcthr}

	First we point out that CalDel is <i>only</i> relevant
	for calibration data taken with charge injection.
	The CalDel setting controlls the time in which the
	charge is injected into the pixels. For real data
	we will have to adjust the timing, e.g. using the
	delay 25 settings fro the trigger. However, for data
	taken with charge injection this delay is important.

	This calibration performs a 2-D scan of CalDel vs VcThr.
	for large VcThr, which corresponds to low thresholds,
	we get lots of noise and the ROC digital readout basically
	shuts down and we don't see any hits. For lower
	values of VcThr we get in the range of CalDel values
	that corresponds to the WBC used. For larger thresholds
	this curve 'bends' to lower values of CalDel. As this
	curresponds to a higher threshold the signal reaches the
	threshold later and hence we need to use a smaller 
	CalDel, i.e. inject the signal earlier.

	\\subsubsection{Output}

	The primary output of this calibration are new
	ROC DAC settings. The only settings that should be
	changedin this calibration are for CalDel and VcThr.

	In addition to the DAC settings the calibration produces
	the output file <tt><b>VcThrCalDelaySummary.txt</b></tt> which
	lists all the ROCs that were used in the calibrations.
	For each of the ROCs there is a corresponding file,
	named like 
	<tt><b>ThrCalDelScan_FPix_BmO_D1_BLD8_PNL2_PLQ1_ROC0.dat</b></tt>.
	You can generate plots of VcThr vs. CalDel using
	the root script <tt><b>thresholdCalDelay.c</b></tt>. An example
	of a plot is shown in Fig.~\\ref{fig:thresholdCalDel}

	
	
	\\includegraphics[width=\\linewidth]{thresholdCalDel}
	
	\\caption{The efficiency for detecting a hit is shown
	as a function of VcThr vs. CalDel. To large values
	of VcThr, corresponding to a low threshold, generates 
	much noise that saturates the digital circuit and no
	hits are seen. The optimal point is indicated in black
	and the blue point indicates the old point from the
	configuration.

	\\label{fig:thresholdCalDel}
	

	\\subsubsection{Example}

	An example configuration file is shown below.
	<pre>

	Mode: ThresholdCalDelay
	Rows:
	10 | 20 
	Cols:
	10 | 20
	VcalHigh
	Scan: VcThr 0 255 8
	Scan: CalDel 0 255 8
	Set: Vcal 50
	Repeat: 10
	ToCalibrate:
	all
	</pre>

	\\subsection{CalDel calibration}

	Again the note from Sect.~\\ref{sect:caldelvsvcthr} apply
	in that CalDel is not relevant for physics data.

	In this calibration we scan CalDel for a series
	of different WBC settings. The creates a pattern
	as indicated in Fig.~\\ref{fig:caldelvsWBC}. As
	a change of one unit of WBC corresponds to 
	24.95ns (40.079 MHz) we can use the change in 
	CalDel for different WBC settings to calibrate
	absolutely what a change of CalDel corresponds
	to in absolute time. 

	We run this calibration with an injection of a large
	signal (255 on the high Vcal range). We then pick
	a Vcal setting that is near the <i>early</i> start
	of the efficient range for the WBC setting. We pick
	an early time so that we retain efficiency for signals
	that are not as strong and takes time to get over 
	threshold. How close to the edge the Vcal setting 
	is taken can be specified by the parameter 
	``EdgeFraction''. Setting this to 0 means that
	you pick the point right at the early edge, setting
	the parameter to 1 means that you select the late
	edge. (This parameter is not yet implemented. By
	default now it the algorithm uses a setting corresponding
	to 0.25.)

	\\subsubsection{Output}

	The CalDel calibration produces new ROC DAC settings
	that update the CalDel settings, all other settings
	should be left unchanged. The calibration also
	generates output to display the region of good 
	efficiency in the WBC vs CalDel. The output can
	be processed to generate plots using the root script
	<tt><b>caldel.c</b></tt>. An example plot is shown in 
	Fig.~\\ref{fig:caldel}

	
	
	\\includegraphics[width=\\linewidth]{CalDelCalibration}
	
	\\caption{
	The efficiency as a function of WBC vs CalDel.
	\\label{fig:caldel}
	



	\\subsubsection{Example}

	An example of a configuration file for the CalDel
	calibration is shown below:

	<pre>
	Mode: CalDelCalibration
	Rows:
	10 | 20 
	Cols:
	10 | 20
	VcalHigh
	Scan: WBC 117 123 1
	Scan: CalDel 0 255 1
	Set: Vcal 250
	Repeat: 2
	ToCalibrate:
	+ all
	</pre>


	\\subsection{Idigi vs. Vsf}

	In this 'calibration' we scan Vsf and measure the
	digital current. This is not really a calibration
	as we don't determine any settings from this. Rather
	what we do is to find a maximum Vsf setting that we
	will use. If Vsf is too large the digital current
	increases. In the configuration for this calibration
	you can set the maximum increase in Idigi that
	you allow using the parameter IdigiMax (units are
	in mA). <i>Not yet implemented, there is a hardcoded
	number of 7 mA now.</i> 

	\\subsubsection{Output}

	This calibration produces the object 
	PixelMaxVsf which is used in the calibration that
	determines Vsf to optimize the linearity. 
	In addition this calibration produces output 
	in a file called idigi.dat. Using the root
	script idigi.c you can generate plots as 
	shown in Fig.~\\ref{fig:IdigivsVsf}.

	
	
	\\includegraphics[width=\\linewidth]{idigi1}
	
	\\caption{The digital current is shown as a function
	of Vsf. }
	\\label{fig:IdigivsVsf}
	

	\\subsubsection{Example}

	The configuration used for the digital scan
	looks like
	<pre>
	Mode:  Idigi
	Rows:
	Cols:
	Vcal:
	200 200 5
	Repeat:
	1
	ToCalibrate:
	+ all
	</pre>

	\\subsection{Linearity vs.~Vsf}

	The ROC DAC setting <b><tt>Vsf</tt></b> affects the linearity of the pixel response vs.~received charge; larger values improve linearity.  
	<b><tt>Vsf</tt></b> also affects the digital current, with higher values increasing the current.  
	We have implemented two algorithms to set <b><tt>Vsf</tt></b> at a value that gives good linearity without drawing excessive power.  
	The first, described in this section, is the algorithm developed at PSI.

	\\subsubsection{Introduction and discussion}

	This algorithm measures linearity from scans of pulse height vs.~<b><tt>Vcal</tt></b> at different values of <b><tt>Vsf</tt></b>. 
	 Examples of these scans are shown in Fig.~\\ref{fig:PH_vs_Vcal_scans}.

	
	
	 \\includegraphics[angle=90,width=0.49\\textwidth]{PH_vs_Vcal_poorLinearity.pdf}
	 \\includegraphics[angle=90,width=0.49\\textwidth]{PH_vs_Vcal_goodLinearity.pdf}
	
	\\caption{Scans of pulse height vs.~Vcal at different values of Vsf.  The scan on the left has poor linearity, and the scan on the right 
	has good linearity.  (Note that these scans come from a detector which has no voltage bias, so the received charge and the slope 
	of the linear section are lower than in a biased detector.)}
	\\label{fig:PH_vs_Vcal_scans}
	

	To quantify the degree of nonlinearity, the scan data are fit with a function
	\\begin{equation} \\label{eq:tanh}
	PH = f(Vcal) = y_{\\rm mid} + y_{\\rm size} \\times \\tanh \\left( \\frac{Vcal - x_{\\rm mid}}{x_{\\rm size}} \\right)
	\\end{equation}
	where $PH$ is the recorded pulse height, $Vcal$ is the input, $(x_{\\rm mid},y_{\\rm mid})$ is the point at the center of the quasi-linear 
	rise region of the hyperbolic tangent, $x_{\\rm size}$ is the horizontal scale of the quasi-linear region, and $y_{\\rm size}$ is the
        vertical scale of that region.

	From this fit, the degree of nonlinearity can be quantified in different ways.  
	The simpler nonlinearity parameter, used by PSI and used by default in this calibration, is $x_{\\rm mid}/x_{\\rm size}$.  
	When this parameter is small, it means that <b><tt>Vcal</tt></b> = 0 lies within the quasi-linear rise region, and hence the response is
	linear for small amounts of injected charge.  
	PSI has used $x_{\\rm mid}/x_{\\rm size} = 1.4$ as the cutoff -- values below 1.4 indicate good linearity.

	An alternate nonlinearity parameter is
	\\begin{equation} \\label{eq:nonlinearityIntegral}
	\\frac{1}{2} \\int_{Vcal_{\\rm min}}^{Vcal_{\\rm max}} dVcal \\left| \\frac{f''(Vcal)}{f'(Vcal)} \\right|
	\\end{equation}
	where $f(Vcal)$ is the hyperbolic tangent function in Eq.~(\\ref{eq:tanh}).  
	This integral is a measure of the vertical change due to curvature divided by the vertical change due to slope over the range of the integral.
	The limits of the integral should be chosen to include the range for which we want good linearity.  
	By default the limits go from <b><tt>Vcal</tt></b> = 50 to <b><tt>Vcal</tt></b> = 400 in low-scale <b><tt>Vcal</tt></b> units, 
	or from 50/7 to 400/7 in high-scale units. 
	 This integral can be evaluated analytically.

	Figure~\\ref{fig:nonlinearityPlots} shows scans of both measures of nonlinearity vs.~<b><tt>Vsf</tt></b>.  
	As seen in the plots, they give similar shapes.  
	This calibration allows the user to use either measure; the default is $x_{\\rm mid}/x_{\\rm size}$.

	
	
	 \\includegraphics[angle=90,width=0.49\\textwidth]{nonlinearityPlot_xmidOverXsize.pdf}
	 \\includegraphics[angle=90,width=0.49\\textwidth]{nonlinearityPlot_integral.pdf}
	
	\\caption{Plots of nonlinearity vs.~Vsf.  On the left, nonlinearity is measured by $x_{\\rm mid}/x_{\\rm size}$, and on the right, 
	it is measured by the integral in Eq.~(\\ref{eq:nonlinearityIntegral}).}
	\\label{fig:nonlinearityPlots}
	

	\\subsubsection{Linearity vs.~Vsf calibration steps}

	This calibration consists of the following steps:
	<ol>
	<li> Scan <b><tt>Vcal</tt></b> and <b><tt>Vsf</tt></b> according to the calibration's configuration.  
	     On each trigger, read out data from each FED's FIFO3.  
	     Record the pulse height, keeping separate scans for different pixels.
	<li> For each scan of pulse height vs.~<b><tt>Vcal</tt></b> (for a given ROC, pixel, and <b><tt>Vsf</tt></b> value), 
	     fit with the function in Eq.~(\\ref{eq:tanh}).  
	     A plot of each scan and fit is written to a ROOT file (see Fig.~\\ref{fig:PH_vs_Vcal_scans}).  
	     If the fit is successful, compute the nonlinearity parameter (either $x_{\\rm mid}/x_{\\rm size}$ or the integral in 
	     Eq.~(\\ref{eq:nonlinearityIntegral})) and add it to a scan of nonlinearity vs.~<b><tt>Vsf</tt></b> for that ROC and pixel.  
	     This scan is also written to a ROOT file (see Fig.~\\ref{fig:nonlinearityPlots}).
	<li> For each scan of nonlinearity vs.~<b><tt>Vsf</tt></b>, determine an optimal <b><tt>Vsf</tt></b>.  
	     This is done by finding the highest<b><tt>Vsf</tt></b> where the scan intersects a nonlinearity threshold. 
	     This threshold may be either absolute or relative, according to the parameter ``<b><tt>absoluteNonlinearityThreshold</tt></b>".  
	     If absolute, the threshold is set by the parameter ``<b><tt>nonlinearityThreshold</tt></b>".  
	     If relative, the threshold is the value of the nonlinearity at the highest <b><tt>Vsf</tt></b> in the scan,
	     multiplied by the parameter ``<b><tt>nonlinearityThreshold</tt></b>".
	<li> For each ROC, examine the optimal <b><tt>Vsf</tt></b>s on the various pixels.  
	     If there are at least 4 pixels, discard any <b><tt>Vsf</tt></b> outliers.  
	     After any discarding, average the <b><tt>Vsf</tt></b> values to determine the <b><tt>Vsf</tt></b> setting for that ROC.
	<li> Compare the <b><tt>Vsf</tt></b> setting on each ROC to the maxVsf setting in the configuration.  
	     If the setting from this calibration exceeds the maximum, reduce <b><tt>Vsf</tt></b> to the maximum allowed.
	<li> Write out new ROC configuration files for the successfully-calibrated
	     ROCs with the new <b><tt>Vsf</tt></b> settings.
	<li> Print out a summary.
	</ol>

	\\subsubsection{Parameters}
	A number of parameters in <b><tt>calib.dat</tt></b> may be used to control the
	calibration.

	The various ``standard" parameters are used in this calibration.  The
	``<b><tt>Repeat:</tt></b>" parameter determines the number of triggers in each step
	of the scan.  The ROC list is used to determine which ROCs are calibrated.

	The scan ranges are specified by lines like
	<pre>
	Scan: Vcal  0 255 5
	Scan: Vsf   0 255 5 mix
	</pre>
	which specify the scan range and step size.  The ``<b><tt>mix</tt></b>'' flag must be enabled for <b><tt>Vsf</tt></b> 
	(or alternatively SingleROC mode must be used); otherwise the calibration will abort.

	The hits specified in <b><tt>Rows:</tt></b> and <b><tt>Columns:</tt></b> will be
	used.  One scan is taken for each pixel with hits.  
	At most two hits per pixel pattern may be specified (or alternatively SingleROC mode must be used); 
	otherwise the calibration will abort.  
	The reason for this restriction is that the FED's spy FIFO3 will overflow if each ROC connected to it has more than two hits.

	Some optional parameters may also be set.  All have default values which will
	be used if the parameter is not set.  These parameters, their defaults, and
	their functionality are given in Table~\\ref{tab:LinearityVsVsfParameters}.

	\\caption{Optional parameters for linearity vs. Vsf calibration.}
	\\label{tab:LinearityVsVsfParameters}
        <center>
	 <table>
  	  <tr>
	   <td> Parameter 	  </td><td> Default </td><td> Description		     		                	   			 </td>
	  </tr>
	  <tr>
	   <td> absoluteNonlinearityThreshold     </td><td> yes    </td><td> Whether the nonlinearity threshold is an   	   			 </td>
	   <td>                         	  </td><td> 	   </td><td> absolute number, or a multiple of the      	   			 </td>
	   <td>                         	  </td><td> 	   </td><td> nonlinearity parameter at maximum <b><tt>Vsf</tt></b> 			 </td>
	   <td> nonlinearityThreshold             </td><td>  1.4   </td><td> Value of the nonlinearity threshold                   			 </td>
	   <td> useIntegrated2ndOver1stDerivative </td><td>  no    </td><td> Whether to use the integral in Eq.~(\\ref{eq:nonlinearityIntegral}) for the </td>
	   <td>                         	  </td><td> 	   </td><td> nonlinearity parameter, instead of $x_{\\rm mid}/x_{\\rm size}$ 		 </td>
	   <td> integralMinVcal                   </td><td>   50/7 </td><td> Lower <b><tt>Vcal</tt></b> bound of the integral (if used)    		 </td>
	   <td> integralMaxVcal                   </td><td>  400/7 </td><td> Upper <b><tt>Vcal</tt></b> bound of the integral (if used)    		 </td>
	 </table>
        </center>

	\\subsection{Vana and time walk}

	<i>This calibration is not yet fully implemented.
	The description below represents what we intend
	to do.</i>

	The idea is to run a scan of Vana vs CalDel. For a large
	charge we will assume that the response of different
	sensors is similar. As for a large charge (the maximum
	that can be injected) the raise time is small it is
	probably a reasonable assumption that we can assume that
	we have a small variation between ROCs. However, for a 
	smaller charge, like 250 on the low Vcal range, this
	is not obviously true. This calibration finds the
	time (absolute) that the Vcal=250 signal is over threshold
	and also finds the slope $dt/d{\\rm Iana}$, or $dt/d{\\rm Vana}$.
	Using this information the ROCs can be unified to one
	time at which a pulse of this strength passes
	over threshold.




	\\subsection{Emulated physics}

	<i>Souvik: add text</i>

	\\subsection{Baseline with emulated data}

	<i>Souvik: add text</i>

	\\subsection{Address levels with emulated data}

	<i>Souvik: add text</i>

	\\section{Detector Startup Procedure}

	Close interaction between the DAQ and DCS (Detector Control System) 
	software systems are foreseen for the detector's startup procedure.
	From the DAQ side, the startup procedure is envisioned to be embedded
	within the "Initializing" and "Configuring" FSM transitions prescribed by
	Run Control. In working through these states, the DAQ system must 
	frequently query
	the DCS system for information on the voltages being applied across various
	detector and front-end elements.

	The XDAQ Supervisor applications mainly involved with this are:

	<ul>
	<li> PixelFECSupervisor: Controls a crate of Pixel FEC boards
	<li> PixelTKFECSupervisor: Controls a crate of Tracker FEC boards
	<li> PixelDCSFSMInterface: Reports the low voltages applied by the DCS 
	      system (simplified to LV_OFF/ LV_ON_REDUCED/ LV_ON)
	</ul>

	PixelFECSupervisor is expected to deal with three voltage states of 
	its underlying elements (the ROCs): LV_OFF/ LV_ON_REDUCED/ LV_ON. Appropriate 
	tristate member data will be added to PixelFECSupervisor to keep 
	track of them.
	PixelTKFECSupervisor is expected to deal with two voltage states of 
	its underlying elements: LV_OFF/ LV_ON. Appropriate bistate member data will 
	be added to PixelTKFECSupervisor to keep track of them.

	The progress through the DAQ's FSM states and transitions for startup 
	and configuration is envisioned as follows:
	<ul>
	<li> PixelFECSupervisor(s) and PixelTKFECSupervisor are initially 
	      in their "Initial" state and await the "Initialize" command.

	<li> On receiving the "Initialize" command, PixelFECSupervisor(s) and 
	      PixelTKFECSupervisor independently query PixelDCSFSMInterface with 
	      the SOAP messages:
	      <pre>
	<fsmStateRequest name="PixelFECSupervisor" type="PxlFEC" instance="1">
	</fsmStateRequest>

	<fsmStateRequest name="PixelTKFECSupervisor" type="TrkFEC" instance="1">
	</fsmStateRequest>
	      </pre>

	respectively.

	<li> The PixelDCSFSMInterface responds with information regarding 
	      the voltage states with a SOAP message of the form:
	      <pre>
	<fsmStateResponse>
	  <state partition="FPix_BmI">LV_ON</state>
	  <state partition="BPix_BpO">LV_OFF</state>
	  ...
	</fsmStateResponse>
	      </pre>

	<li> The PixelFECSupervisor(s) and PixelTKFECSupervisor update 
	      their tri- and bi-state member data
	      according to the response from PixelDCSFSMInterface. This 
	      concludes the "Initializing" transition
	      and both the PixelFECSupervisor(s) and PixelTKFECSupervisors 
	      land in their "Halted" states.

	<li> On receiving the "Configure" command, PixelFECSupervisor(s) 
	      and PixelTKFECSupervisor
	      check the status of their member data. If the appropriate 
	      voltages are set then they go ahead
	      with step 6 else transition to the "Error" state.

	<li> PixelFECSupervisor queries for the currents and then 
	      loads the ROCs' DAC settings.
	      The currents are queried again to make sure that  a change in 
	      the current consumption is as expected.
	      If this is seen then we proceed to step 7 or else we 
	      transition PixelFECSupervisor to the "Error" state.

	<li> PixelFECSupervisor sends a SOAP message to PixelDCSFSMInterface to raise the 
	      Digital Voltages.
	      The PixelDCSFSMInterface responds back with the raised values of the Digital Voltages.
	      PixelFECSupervisor resets its
	      tristate member data if this went fine or else 
	      transitions to its "Error" state.

	<pre>
	<fsmStateNotification>
	  <state partition="FPix_BmI">ReadoutCHIPS_INITIALIZED</state>
	  <state partition="BPix_BpO">ReadoutCHIPS_INITIALIZED</state>
	</fsmStateNotification>
	</pre>


	<li> PixelFECSupervisors load their ROCs' DAC, mask and trim settings.
	      PixelFECSupervisor loads the slow I2C settings for CCU 
	      boards, Port Cards etc.

	<li> PixelFECSupervisor(s) and PixelTKFECSupervisor land in 
	      their "Configured" state.

	</ul>

	A SOAP message callback is created in PixelFECSupervisor and 
	PixelTKFECSupervisor
	that receive independent FSM state notifications from 
	PixelDCSFSMInterface and update
	their tri/bi-state member data. This may be useful in case a 
	voltage state is achieved
	by the DCS system after the DAQ system has initialized but 
	hasn't begun configuring.

	For the PixelFECSupervisor to read out the current I suggest that 
	this is done by calling the PixelSupervisor. The PixelSupervisor
	will have all the configuration information needed to read the
	currents.


    __________________________________________________________________________________
    \page page5 5- Appendix

     
      \section page5Sect1 FED phase and delay calibration
	\\label{sect:phaseanddelay}

	This section will describe some aspects of determining the 
	so called 'phase' and 'delay' of the FED. The sample 
	plots shown in this section are taken from runs on the 
	FPIX pilot run detector. this was done using a version 4 FED
	with the Aug. 22, 2007 firmware version.

	In order to get the transparent data to 'look' OK I had
	to send an LRES before each trigger. Will Johns and I had 
	long email exchanges trying to understand this. I think
	that the final conclusion was that the FED state machine
	gets confused when the input data is non standard. In the
	scans over phases and delays there are certain settings that
	are invalid, i.e., that you try to read out the ADC before the
	data is available. At the end of this section I will discuss
	two issues that I noticed in looking at the transparent data.

	For the above reason we also turn off the automatic baseline
	correction to avoid it getting confused if you seend non valid 
	data or if you don't have correct address levels.

	In these tests we take 10 triggers for each delay and phase
	setting. I'll show plots, as in Fig.~\\ref{fig:phasedelayraw},
	where for each of the two possible phases the profile
	histogram shows the adc value as a function of clock+delay/16.
	The third plots just shows the two plots on top of each other.
	
	
	\\includegraphics[width=\\linewidth]{phaseAndDelayPlotRaw_channe_1_1}
	
	\\caption{This figure shows on top the adc value as a function of 
	clock+delay/16 for phase=0 and the same plot for phase=1 in the 
	middle. The two plots are overlaid at the bottom.}
	\\label{fig:phasedelayraw}
	
	We see that 
	there are certain values of the delays that produce garbage
	as you try to read out the ADC before the data is available.
	To identify the invalid combinations of phase and delay I
	calculate the rms for the different phase and delay settings
	in the first 20 clock cycles, i.e. before the TBM header arrives.
	Based on the rms distribution it is seen that for phase=0 that
	we got invalid data with delays of 1, 2, and 3, while for
	phase=1 the delays of 10, 11, and 12 generate invalid data.
	From now on I will reject these combinations. (In the plots I set the
	adc value to 0.)

	After rejecting the invalid phase and delay combinations we now
	have a signal that looks as what is shown in Fig.~\\ref{fig:phasedelayvalid}.
	
	
	\\includegraphics[width=\\linewidth]{phaseAndDelayPlotPurged_channe_1_1}
	
	\\caption{This figure shows on top the adc value as a function of 
	clock+delay/16 for phase=0 and the same plot for phase=1 in the 
	middle. The two plots are overlaid at the bottom. Here I have set the
	adc value to 0 for the combinations of clock and phase that are not
	valid.}
	\\label{fig:phasedelayvalid}
	
	The remaining signal still has artifacts due to when the
	adc latches on to the signal such that it looks like the signal
	is not read out in order. This is corrected by 'reordering' the data
	within a clock. I shifted the phase=0 events backward by 3 delay steps
	and the phase 1 events forward by 3 delay steps. This makes the
	signal continuous as shown in Fig.~\\ref{fig:phasedelayshifted}.
	
	
	\\includegraphics[width=\\linewidth]{phaseAndDelayPlotShifted_channe_1_1}
	
	\\caption{This figure shows on top the adc value as a function of 
	clock+delay/16 for phase=0 and the same plot for phase=1 in the 
	middle. The two plots are overlaid at the bottom. Here the
	data within a clock has been ordered to give a continuous data
	signal.}
	\\label{fig:phasedelayshifted}
	


	The last step is to align the data so that the phase=0 and phase=1 
	data overlaps. I do this by shifting the data for the events with phase=1
	by 10 delay steps. The final result is shown in 
	Fig.~\\ref{fig:phasedelayfinal}. For the bins in the plot where there
	is data from both phase=0 and phase=1 we see that there is excellent
	agreement. We also not that the signal undershoots in a transition 
	from black to ultrablack and that it overshoots on the reverse transition.
	
	
	\\includegraphics[width=\\linewidth]{phaseAndDelayPlot_channe_1_1}
	
	\\caption{This figure shows on top the adc value as a function of 
	clock+delay/16 for phase=0 and the same plot for phase=1 in the 
	middle. The two plots are overlaid at the bottom. Here the phase=1
	data has been shifted so that it overlaps with the phase=0 data.}
	\\label{fig:phasedelayfinal}
	


	To determine a best delay I look at the combined data - where I average
	the bins that has both phase=0 and phase=1 contributions - and calculate
	a difference for bin $i$ by taking the difference between bin $i-1$ 
	and $i+1$.
	I calculate this difference for the 25 MHz clock cycles from clock 27 to 100.
	I add the magnitude of these differences for all bins that corresponds
	to the same delay. I pick the smallest such sum of differences for the
	different delay as the optimal choice. If more than one phase is allowed
	I pick the choice that is farthest from the invalid delay for that phase.

	A new alogorithm has been implmented that determines the phase
	to be right at the edge of the transition from black to ultrablack
	in the TBM trailer. You can still run the old algorithm by setting
	the parameter 'oldMode' to 'Yes'.


	Looking at the 8 channels that were connected to the pilot run detector
	I find that the results are very consistent. The phase is either 0 or
	15 in the (aligned delay) for the raw delay setting this corresponds
	to 2 or 3 for phase=1.

	Open questions: Is the same set of phases and delays illegal on all
	FEDs and channels? Also, are the shifts that are needed to time-order
	the data the same on all FEDs and channels? Looking at more data will
	resolve this. It is easy to test that the data in the two phases are 
	compatible by forming a $\\chi^2$.

	The code was written as a root macro. I will 'transplant' this code
	into xdaq so we can run it automatically to produce the phase and delay
	settings needed.

	However, looking at this I observed an odd feature. 
	This is illustrated in Fig.~\\ref{fig:phasedelaylatedata}.
	
	
	\\includegraphics[width=\\linewidth]{phaseAndDelayPlot_channe_10_1_latedata}
	
	\\caption{Here you see that for clocks in and after the TBM trailer that
	there is a feature in that some delays are oscillating. This 'excitation'
	seems to decay of after $O(20)$ clocks. }
	\\label{fig:phasedelaylatedata}
	
	In Fig.~\\ref{fig:phasedelaylatedatazoom} is a close up of the 
	region with the noise.
	
	
	\\includegraphics[width=\\linewidth]{phaseAndDelayPlot_channe_10_1_latedatazoom}
	
	\\caption{Zooming in you can see that data in the two phases
	both agree on the shape of this feature. }
	\\label{fig:phasedelaylatedatazoom}
	
	Here you can see that there is 'wiggle' in the data that is large compared
	to the rms, as indicated by the error. This wiggle seems to persist
	for many clock cycles after the TBM trailer. However, it was not present
	in the black data before the data train. It seems to first start
	in the TBM trailer when the UB signal is generated. With the
	pilot run detector we are using 8 channels 
	(1, 2, 3, 4, 7, 8, 9, and 10). I see the same feature on 
	almost all channels, though they are not as strong on channel 1, 7,
	and 9.




	
	
	\\includegraphics[width=0.48\\linewidth]{graph_FPix_BpI_D1_PRT1_FPix_BpI_D1_BLD1_PNL1_0}
	\\includegraphics[width=0.48\\linewidth]{graph_FPix_BpI_D1_PRT1_FPix_BpI_D1_BLD1_PNL1_1}
	\\includegraphics[width=0.48\\linewidth]{graph_FPix_BpI_D1_PRT1_FPix_BpI_D1_BLD1_PNL1_2}
	\\includegraphics[width=0.48\\linewidth]{graph_FPix_BpI_D1_PRT1_FPix_BpI_D1_BLD1_PNL1_3}
	
	\\caption{This figure shows the results of scans for delay25 settings on
	the Cornell test stand. The upper left plots shows (large black dots) the
	region for which the return data was valid when sending a ROC command (CalPix).
	The upper right plot shows the valid region when sending a TBM command 
	(tbm speed). The lower left shows the region of success when sending a 
	roc init and the lower right shows the region of success with a roc trim
	load command. As is seen, the working region is smaller for the long
	commands. The red and blue points indicates the algorithm used to select
	the operating point. Need to check with Jennifer what this is doing.}
	\\label{fig:scanDelay25}
	

      \section page5Sect2 Calibration Organization

	The calibrations all share a similar format.
	<ul>
	<li> The PixelSupervisor controls a loop over 'events' and coordinates
	      the activity of the FED, FEC, TKFEC, and TTC supervisors.
	<li> Each calibration needs to do some initialization before processing
	      the event data.
	<li> During event processing data is acquired and processed.
	<li> After all event data is taken it is analyzed and the results are
	      saved.
	</ul>
	This section will describe a <i>proposal</i> for how to formalize this process.
	A first step in this this direction was taken when the calibration classes
	were broken out from the the PixelSupervisor and the PixelFEDSupervisor.
	This first step was almost trivial as it just copied the code out to
	separate classes. There are a few more changes we should make that will
	allow us to run these jobs in workloops. Among other things, this will 
	allow us to look
	at the progress of the calibrations from the web browser.

     \subsection page5Sect2Sub1 PixelSupervisor calibration code

	We change the <tt><b>PixelCalibrationBase</b></tt> class to have
	the interface below.
	<pre>
	class PixelCalibrationBase : public PixelSupervisorConfiguration, 
		    public SOAPCommander {
	 public:

	  PixelCalibrationBase( const PixelSupervisorConfiguration &,
				   const SOAPCommander& soapCommander  );

	  virtual ~PixelCalibrationBase(){};

	  virtual void beginCalibration();

	  virtual bool calibrationEvent();

	  virtual void endCalibration();

	 protected:

	  private:

	  // PixelCalibrationBase Constructor
	  PixelCalibrationBase(const SOAPCommander& soapCommander);

	};
	</pre>

	The method <tt><b>begin()</b></tt> should do any initialization that 
	is needed before processing any triggers. The method <tt><b>event()</b></tt>
	is called repeatedly until it returns true, this indicates that
	the calibration has come to an end. 
	<i>Souvik, is this sufficient to allow implement this running in
	a workloop?</i>
	Then the <tt><b>end()</b></tt>
	method is invoked to perform any analysis of the acquired data.


	More details on what these methods needs to do will be
	discussed below.


     \subsection page5Sect2Sub2 PixelFEDSupervisor calibration code

	Similarly, I suggest a more general structure for the calibration 
	code that runs in the PixelFEDSupervisor.

	<pre>
	class PixelFEDCalibrationBase : public PixelFEDSupervisorConfiguration, 
		    public SOAPCommander {
	 public:

	  PixelFEDCalibrationBase( const PixelFEDSupervisorConfiguration &,
				   const SOAPCommander& soapCommander );

	  virtual ~PixelFEDCalibrationBase(){};

	  virtual xoap::MessageReference beginCalibration(xoap::MessageReference msg);

	  virtual xoap::MessageReference calibrationEvent(xoap::MessageReference msg);

	  virtual xoap::MessageReference endCalibration(xoap::MessageReference msg);

	  //Should really not be here....
	  unsigned int TransparentDataStart (unsigned long *buffer);


	 protected:

	  //SOAPCommander* theSOAPCommander_;

	 private:

	  // PixelCalibrationBase Constructor should neve be called
	  PixelFEDCalibrationBase(const SOAPCommander& soapCommander);

	};
	</pre>

	Again the three methods <tt><b>beginCalibration()</b></tt>, 
	<tt><b>calibrationEvent()</b></tt>, and <tt><b>endCalibration()</b></tt>
	corresponds to the pre calibration data taking, processing of trigger
	and the post data taking analysis respectively. I suggest that
	these methods are bound to soap messages that invokes
	the implemented methods.

	In particular we should move the code that sets the mode
	and control registers to the <tt><b>beginCalibration()</b></tt> method.
	This will allow us to move out code from the PixelFEDSupervisor
	that is specific to different calibrations. <i>Or we split
	out the mode and control register settings to a new configuration
	object.</i>

     \subsection page5Sect2Sub3 Implementation of algorithms

	During the configuration step the <tt><b>PixelSupervisor</b></tt> and
	<tt><b>PixelFEDSupervisor</b></tt>
	instantiates the Calibration class for the calibration objects.
	When we go to Run the PixelSupervisor invokes the <tt><b>beginCalibration()</b></tt>
	method. This method is responsible for sending the <tt><b>beginCalibration()</b></tt>
	message to the PixelFEDSupervisors. 

	After this the PixelSupervisor should execute the <tt><b>calibrationEvent()</b></tt>
	in a workloop until it has completed. Again, the code executed in the
	PixelFEDSupervisor is responsible for calling the appropriate 
	supervisors. This gives the maximal flexibility in the calibration
	algorithm.

	Last, the <tt><b>endCalibration</b></tt> method in the <tt><b>PixelSupervisor</b></tt> is
	invoked to complete the analysis of the collected data and report
	the results.

	In addition it would be nice to take out the code from the PixelSupervisor
	and the PixelFEDSupervisor that select the calibration type. One
	way of doing this is to create a 'factory' for calibrations in the 
	PixelCalibrations package. This factory would accept a string from
	the calibration mode and create the calibration object and return
	it to the PixelSupervisor and the PixelFEDSupervisor. Besides
	simplifying the code in these supervisors (they will not need to \\#include
	all the calibrations header files) it will also separate out dependencies.


     \subsection page5Sect2Sub4 Outstanding tasks and improvements

	I will divide these task into three different categories.
	The first is algorithm/calibration development. The second
	is 'operations', the third is code improvements.

     \subsubsection page5Sect2Sub4Sub1 Calibration development
	<ul>
	<li> Implement algorithm for time walk. Some of the tools are
	      available. Need to understand how to analyze the data
	      and set parameters.
	<li> Adjust AOH gain setting. Need to discuss a strategy for this.
	<li> Need to fix the delay25 calibration; it wraps around.
	<li> Linearity adjustment. Steve started to look at Vsf and Vhlddel.
	<li> Adjust the ROC analog signal offset and gain. Want to keep the
	      lowest level well above UB, and the maximum near 255 (or 1024).
	<li> In the address level determination if the highest level hit 1023 it 
	      will not be detected. Should allow this.
	</ul>

     \subsubsection page5Sect2Sub4Sub2 Operation improvements

	<ul>
	<li> Migrate calibration algorithms to use root objects, like
	      histograms. This will allow us to write out root files
	      with the calibration results as well as monitoring
	      the progress of calibrations.
	<li> Tools to view the calibration results should be 
	      migrated to look at root files.
	<li> Deploy database. 
	<li> Use filebased interface and aliases to nor write over 
	      old files. This is basically done. But should modify the
	      writing of files so that all files in the configuration
	      is written out again. Otherwise it will be to hard to used.
	      This is not very complicated, but not sure what is the 
	      best strategy.
	<li> Deploy the error logger to make sure that we send relevant
	      and not to verbose messages.
	<li> Have to run with the FEDSpySupervisor.
	<li> Run with the power-on sequence. This is work in progress
	      now and a first try will take place during the week of 
	      Jan. 28, 2008.
	<li> We should properly initialize the CCU. 
	<li> We should try out the schemes for reconfiguring a CCU ring
	      to drop a CCU.
	<li> Is it possible that we can program ROCs on one panel, or blade,
	      such that we can burn the fuse on the adapter board?
	<li> We have to try out the 'popcon' feature for calibrations.
	<li> Embed the 'private' words in the FED data. Have code example
	      now from Will. Need to modify the rawToDigi code to unpack
	      this information.
	</ul>

     \subsubsection page5Sect2Sub4Sub3 Code improvements

	<ul>
	<li> Move DCU readout workloop to configure transition.
	<li> Calibration algorithms should run on separate threads.
	      This is mostly implemented now. Some calibrations 
	      still need to migrate to executing the calibration
	      in 'steps', and not just as on call. 
	<li> should use dynamic cast instead of static cast.
	<li> Further cleanup in calibrations. A number of the
	      calibrations contains a large amount of duplication.
	<li> Some code like the FEDInterface and FEDCard is too verbose.
	      Need to review printouts.
	<li> There are some exceptions we need to catch. For example
	      if we try to talk to a non-existing FED base address we
	      should catch the exception and not just crash.
	<li> Should the supervisor applications be self updating like
	      the trigger supervisor applications? This would then allow
	      to automatically update progress status during a calibration
	      and handle when a calibration is complete.
	<li> The ROC status should be respected. This would, e.g., allow
	      us to not generate a failed calibraton when one of the
	      ROCs can't generate hits.
	<li> More consistency checking needed; in particular for the AOH
	      initialization. Should only initialize portcards that are
	      used.
	</ul>

    __________________________________________________________________________________
    \page page6 6- Conclusions 
     
     This page is just a placeholder for the time being

*/