Main Page | Modules

Read/write interface


Functions

dyn_int fwUkl1_parseReadRegisterSections (const dyn_char &dcData, unsigned numSections, unsigned sectionGap, unsigned startBit, unsigned length, bool fpga, dyn_string &exceptionInfo)
int fwUkl1_parseReadRegister (dyn_char dcData, unsigned startBit, unsigned length, bool fpga, dyn_string &exceptionInfo)
string fwUkl1_convertMacToHex (const string &macAddress, dyn_string &exceptionInfo)
string fwUkl1_convertByteToMac (const dyn_char &macAddress, dyn_string &exceptionInfo)
string fwUkl1_convertIpToHex (const string &ipAddress, dyn_string &exceptionInfo)
string fwUkl1_convertByteToIp (const dyn_char &ipAddress, dyn_string &exceptionInfo)
void fwUkl1_convert32To16BitWords (dyn_char &dcData, dyn_string &exceptionInfo)
string fwUkl1_convertByteToHexLittleEndian (const dyn_char &dcData, dyn_string &exceptionInfo)
void fwUkl1_padString (string &sData, unsigned numBytes)
dyn_dyn_string fwUkl1_parseBroadcastData (const dyn_string &origData, dyn_string &exceptionInfo)
void fwUkl1_parseBeFpgaWriteRegisters (string ukl1Name, dyn_string &registerNames, dyn_string sData, dyn_dyn_char &ddcData, dyn_dyn_char &masks, dyn_string &exceptionInfo)
void fwUkl1_parseBeFpgaReadRegisters (string ukl1Name, const dyn_string &registerNames, dyn_dyn_char ddcData, dyn_string &data, const dyn_int &callStatusList, dyn_string &exceptionInfo)
void fwUkl1_parseFeFpgaWriteRegisters (string ukl1Name, unsigned feFpga, dyn_string &registerNames, dyn_string sData, dyn_dyn_char &ddcData, dyn_dyn_char &masks, dyn_string &exceptionInfo)
void fwUkl1_parseFeFpgaReadRegisters (string ukl1Name, unsigned feFpga, const dyn_string &registerNames, dyn_dyn_char ddcData, dyn_string &data, const dyn_int &callStatusList, dyn_string &exceptionInfo)
void fwUkl1_parseFeFpgaChannelWriteRegisters (string ukl1Name, unsigned channel, unsigned feFpga, dyn_string &registerNames, dyn_string sData, dyn_dyn_char &ddcData, dyn_dyn_char &masks, dyn_string &exceptionInfo)
void fwUkl1_parseFeFpgaChannelReadRegisters (string ukl1Name, unsigned channel, unsigned feFpga, const dyn_string &registerNames, dyn_dyn_char ddcData, dyn_string &data, const dyn_int &callStatusList, dyn_string &exceptionInfo)
void fwUkl1_parseGbeWriteRegisters (string ukl1Name, dyn_string &registerNames, dyn_string sData, dyn_dyn_char &ddcData, dyn_dyn_char &masks, dyn_string &exceptionInfo)
void fwUkl1_parseGbeReadRegisters (string ukl1Name, const dyn_string &registerNames, dyn_dyn_char ddcData, dyn_string &data, const dyn_int &callStatusList, dyn_string &exceptionInfo)
void fwUkl1_parseGbePortWriteRegisters (string ukl1Name, unsigned port, dyn_string &registerNames, dyn_string sData, dyn_dyn_char &ddcData, dyn_dyn_char &masks, dyn_string &exceptionInfo)
void fwUkl1_parseGbePortReadRegisters (string ukl1Name, unsigned port, const dyn_string &registerNames, dyn_dyn_char ddcData, dyn_string &data, const dyn_int &callStatusList, dyn_string &exceptionInfo)
void fwUkl1_parseTtcrxWriteRegisters (string ukl1Name, dyn_string &registerNames, dyn_string sData, dyn_dyn_char &ddcData, dyn_dyn_char &masks, dyn_string &exceptionInfo)
void fwUkl1_parseTtcrxReadRegisters (string ukl1Name, const dyn_string &registerNames, dyn_dyn_char ddcData, dyn_string &data, const dyn_int &callStatusList, dyn_string &exceptionInfo)
void fwUkl1_beFpgaWrite (const string &ukl1Name, bool writeRecipe, const dyn_string &recipeNameAndType, dyn_string registerNames, const dyn_string &data, bool verifyWrite, dyn_string &exceptionInfo)
void fwUkl1_beFpgaRead (const string &ukl1Name, bool readRecipe, const string &recipeName, dyn_string registerNames, dyn_string &data, dyn_string &exceptionInfo)
void fwUkl1_feFpgaWrite (string ukl1Name, unsigned feFpga, bool writeRecipe, const dyn_string &recipeNameAndType, dyn_string registerNames, const dyn_string &data, bool verifyWrite, dyn_string &exceptionInfo)
void fwUkl1_feFpgaRead (string ukl1Name, unsigned feFpga, bool readRecipe, const string &recipeName, dyn_string registerNames, dyn_string &data, dyn_string &exceptionInfo)
void fwUkl1_feFpgaChannelWrite (string ukl1Name, unsigned channel, unsigned feFpga, bool writeRecipe, const dyn_string &recipeNameAndType, dyn_string registerNames, const dyn_string &data, bool verifyWrite, dyn_string &exceptionInfo)
void fwUkl1_feFpgaChannelRead (string ukl1Name, unsigned channel, unsigned feFpga, bool readRecipe, const string &recipeName, dyn_string registerNames, dyn_string &data, dyn_string &exceptionInfo)
void fwUkl1_gbeWrite (string ukl1Name, bool writeRecipe, const dyn_string &recipeNameAndType, dyn_string registerNames, const dyn_string &data, bool verifyWrite, dyn_string &exceptionInfo)
void fwUkl1_gbeRead (string ukl1Name, bool readRecipe, const string &recipeName, dyn_string registerNames, dyn_string &data, dyn_string &exceptionInfo)
void fwUkl1_gbePortWrite (string ukl1Name, unsigned port, bool writeRecipe, const dyn_string &recipeNameAndType, dyn_string registerNames, dyn_string data, bool verifyWrite, dyn_string &exceptionInfo)
void fwUkl1_gbePortRead (string ukl1Name, unsigned port, bool readRecipe, const string &recipeName, dyn_string registerNames, dyn_string &data, dyn_string &exceptionInfo)
void fwUkl1_ttcrxWrite (string ukl1Name, bool writeRecipe, const dyn_string &recipeNameAndType, dyn_string registerNames, dyn_string data, bool verifyWrite, dyn_string &exceptionInfo)
void fwUkl1_ttcrxRead (string ukl1Name, bool readRecipe, const string &recipeName, dyn_string registerNames, dyn_string &data, dyn_string &exceptionInfo)
string fwUkl1_getUkl1SerialNumber (const string &ukl1Name, dyn_string &exceptionInfo)
dyn_int fwUkl1_getUkl1Temperatures (string ukl1Name, dyn_string &exceptionInfo)
unsigned _fwUkl1_fpgaizeAddress (unsigned addr)
void _fwUkl1_write (const string &ukl1Name, const dyn_string &registerNames, const dyn_dyn_char &ddcData, const dyn_dyn_char &masks, bool verifyWrite, dyn_string &exceptionInfo)
void _fwUkl1_saveRecipe (const string &ukl1Name, const dyn_string &recipeNameAndType, const dyn_string &registerNames, const dyn_dyn_char &ddcDataAndMask, int regType, dyn_string &exceptionInfo)
void _fwUkl1_verifyWrite (dyn_string registerNames, dyn_dyn_char writtenData, dyn_dyn_char masks, dyn_dyn_char readData, dyn_string &exceptionInfo)

Detailed Description

This section provides functions for communicating with the hardware on a specified UKL1 board, with the board always identified by its name as found in the DIM server. It provides the ability to access all registers on the hardware and to perform other hardware related tasks such as resetting or reloading the UKL1s. It also provides access to the recipes saved for the UKL1 hardware type. This is done via the UKL1 board name as found in the DIM server and the name of the specific recipe that is being address. Recipe and hardware access are setup such that they are almost identical function prototypes and it is only the addition of the recipe name and choice of verifying the hardware writes that causes them to be different. This hides the subtlies of writing to the hardware of database from the User.

There are two methods for reading the values a register. It can either be done directly or via monitoring. In the case of direct reading the function fwCcpc_read() or fwHw_getRecipe() is used and the values returned by this function are parsed by fwUkl1_parseReadRegister()to remove the relevant bits from the register. It removes a continuous sections of bits and returns it as a hex string, this can then be converted into an appropriate display value. Further multiple sections of the defined size can be removed, via fwUkl1_parseReadRegisterSections(). In the case of monitoring callback functions can be setup in order to parse the data of a given data point only when it changes and again fwUkl1_parseReadRegister can be used to manipulate the register data to get at the desired information or fwUkl1_parseReadRegisterSections() if data is to be removed for example in the case of FE FPGA broadcast data. A read, using fwCcpc_read, can be used to force a reset of all monitored value, in this case the data returned by fwCcpc_read can just be ignored. This method is recommended for dealing with status registers. The library provides a function to read all the registers for a given area of the UKL1 e.g. all the BE FPGA register, and then returns them in a predefined formatted state. This is to be used in the case that monitoring is not required or the User does not wish to know or does not know the data is organised across the registers. The values returned will be in strings will often contain a description of the state rather than just a number. Again values for similar element e.g. the input channel disable states can be returned as comma separated values. This method is recommended for reading from configuration registers.

The library provides a mechanism for writing to the registers on the UKL1. It provides a wrapper for the fwCcpc_write mechanism however it provides a layer of abstraction that does not require the User to understand the layout of the registers and which registers contain multiple settings. It takes a string that typically describes the registers state and is identical to the value read in the case of the read/write configuration registers. This function is advised to be used when writing to the configuration registers.

All errors are returned by the framework defined exception handling mechanism taking an argument exceptionInfo by reference, which will contain details of an errors that occurred.


Function Documentation

unsigned _fwUkl1_fpgaizeAddress unsigned  addr  ) 
 

In order to write to specific registers on the FPGAs we must first convert the address to include the address of the FPGAs from the glue card perspective.

Parameters:
addr Address of the register to be written to.
Returns:
unsigned Full address of the FPGA register.

void _fwUkl1_saveRecipe const string &  ukl1Name,
const dyn_string &  recipeNameAndType,
const dyn_string &  registerNames,
const dyn_dyn_char &  ddcDataAndMask,
int  regType,
dyn_string &  exceptionInfo
 

Save a list of recipes to the given recipe, which is of the given type. The data should contain the actual value that would be written to the hardware and include the mask that should be used when writing the data.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
recipeNameAndType Two element array containing:
  • Element 1 - The name of the recipe to save the data to. It must be of the form "RUN_TYPE/FsmAction", where RUN_TYPE is descriptive of the type of run the settings are saved for e.g. PHYSICS, CALIBRATION; FsmAction is the action of FSM state transition where the recipe should be loaded e.g. Configure, the first letter only should be capitalised.
  • Element 2 - The second element contains the recipe type that it is to be saved to, this can be anything provided it already exists.
registerNames dyn_string that contains the name of the HwTypeCCPCUKL1 datapoint element to be written to, which corresponds to the appropriate hardware register.
ddcDataAndMask Each element of this array contains an array of char that make up the words that are to be written to the register in the form required by a fwCcpc_write and this includes the mask that is to be used for the data.
regType Hardware register type that the data is being saved for. It accepts the constants defined by the fwHw.ctl lib.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.

void _fwUkl1_verifyWrite dyn_string  registerNames,
dyn_dyn_char  writtenData,
dyn_dyn_char  masks,
dyn_dyn_char  readData,
dyn_string &  exceptionInfo
 

Reads from the registers on the L1 board to ensure that the data just written has been written successfully.

Parameters:
registerNames Names of the registers that were written to.
writtenData The data that was written to the registers that the read back values should be compared against.
masks Any masks that should be applied to the read data, such that only specific bits in a register are compared against the write bits.
readData The data that was read back from the registers to compare against the written data.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.
This function is designed to check the data written and read using the fwCcpc_writeRead function.

void _fwUkl1_write const string &  ukl1Name,
const dyn_string &  registerNames,
const dyn_dyn_char &  ddcData,
const dyn_dyn_char &  masks,
bool  verifyWrite,
dyn_string &  exceptionInfo
 

Writes the given data to the given UKL1 board. The masks are applied when writing the data to ensure that only specific bits of a register are written to.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
registerNames dyn_string that contains the name of the HwTypeCCPCUKL1 datapoint element to be written to, which corresponds to the appropriate hardware register.
ddcData Each element of this array contains an array of char that make up the words that are to be written to the register in the form required by a fwCcpc_write.
masks Each element contains a bit mask that is applied when writing the corresponding element in the ddcData array to the corresponding register in the registerNames array. It ensure that only the desired bits are written to in the register.
verifyWrite If this is set to TRUE write will be verified to be successful.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.

void fwUkl1_beFpgaRead const string &  ukl1Name,
bool  readRecipe,
const string &  recipeName,
dyn_string  registerNames,
dyn_string &  data,
dyn_string &  exceptionInfo
 

This reads from a given set of registers on the BE FPGAs.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
readRecipe If TRUE then the function will read the settings from the given recipe name and return the settings contained within. FALSE and the returned values will come directly from the hardware registers.
recipeName Name of the recipe to save the configuration information to if writeDb=TRUE, not used if writeDb=FALSE. The recipe must be of the form "RUN_TYPE/FsmAction", where RUN_TYPE is type of run that the recipe is to be loaded e.g PHYSICS, CALIBRATION, can take any value, but should be descriptive of the type of run the recipe settings represent; FsmAction is the action in the FSM when these settings should be loaded e.g. Configure if the recipe is to be used to moved to the READY state, typically only the first letter is upper case.
registerNames dyn_string containing the names of the registers that need to be read. It need not contain the full path of the register i.e. the datapoint name and hardware chip (BeFpga, GBE) must be neglected. If the requested register does not exist in the recipe an empty string will be returned in the data, but no error. If it does not exist for hardware reads then it will fail and exceptionInfo will contain a PVSS error for that register.
data dyn_string returned by reference that contains a string representing the value in the register. The details of this string can be found in fwUkl1_parseBeFpgaReadRegister() documentation. Will return `Fail' in the event the read is not successful.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void

void fwUkl1_beFpgaWrite const string &  ukl1Name,
bool  writeRecipe,
const dyn_string &  recipeNameAndType,
dyn_string  registerNames,
const dyn_string &  data,
bool  verifyWrite,
dyn_string &  exceptionInfo
 

Writes to a given set of UKL1 registers. Data should be in a form acceptable to the fwUkl1_parseBeFpgaWriteRegisters() as it will first be passed through this function before being written to the hardware.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
writeRecipe If TRUE then the function will write the given register settings to the configurationDB recipe given by recipe name. FALSE it will write the register settings to the UKL1 board.
recipeNameAndType Two element array containing:
  • Element 1 - The name of the recipe to save the data to. It must be of the form "RUN_TYPE/FsmAction", where RUN_TYPE is descriptive of the type of run the settings are saved for e.g. PHYSICS, CALIBRATION; FsmAction is the action of FSM state transition where the recipe should be loaded e.g. Configure, the first letter only should be capitalised.
  • Element 2 - The second element contains the recipe type that it is to be saved to, this can be anything provided it already exists. This array is only required if writeRecipe=TRUE, otherwise it can be empty.
registerNames dyn_string containing the names of the registers that need to be read. It need not contain the full path of the register i.e. the datapoint name and hardware chip (BeFpga, GBE) must be neglected. Care must be taken that the registers requested exist.
data By default a 16-bit value that is to be written to the register represented as a 4-character hex string, it need not be zero padded. Certain settings accept or require an alternative format as described in the fwUkl1_parseBeFpgaRegisters function.
verifyWrite If this is set to TRUE write will be verified to be successful. Not used if writeDb=TRUE.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void
If the recipe name does not exist it will be created. If the recipe type does not exist then the recipe may lose its type and all data associated with it. No checks are performed on the recipe type at present.

void fwUkl1_convert32To16BitWords dyn_char &  dcData,
dyn_string &  exceptionInfo
 

This takes the data that is read by from the L1 board FPGAs (LBUS), which is read as a series of 32-bit words, and converts it to a series of 16-bit words can then be decoded to return the register value.

Parameters:
dcData The dyn_char array that contains the bytes read back from the hardware, will have the upper 2-bytes removed from the array. Assume byte ordering that matches that done read by the FW CCPC library. Return by reference.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
dyn_char The dyn_char that now has its bytes in an order that can be decoded by the fwCcpc library to return a string representing the hex number.
The function performs two tasks. First it considers the byte array as a group of 32-bit numbers and removes the upper two bytes to reduce them to a 16-bit number. The resulting array must then be word swapped, however the words must maintain their internal byte ordering.

string fwUkl1_convertByteToHexLittleEndian const dyn_char &  dcData,
dyn_string &  exceptionInfo
 

Converts an array of bytes into a hex string and treats the dyn_char array as if it were little endian.

Parameters:
dcData The array of bytes to be converted.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
string Hex string of the dyn_char. Will return `Fail' if the data could not be converted.

string fwUkl1_convertByteToIp const dyn_char &  ipAddress,
dyn_string &  exceptionInfo
 

Takes an array of bytes, and returns them as a full stop delimited IP address.

Parameters:
ipAddress The array containing the bytes to be parsed.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
string Expects a 4 element array. Returns `Fail' if the input data is missformed.
This code requires that the extra bytes generated from a fwCcpc_read() are first removed, via fwUkl1_convert32To16BitWords(). Generally it is expected that this function will only be used internally and fwUkl1_parseBeFpgaReadRegister() will be used if dealing with the BE FPGA registers. It is not defined an internal function as it mirrors the convert IP to byte function, which is not internal.

Example

   (...)
   //Fictional UKL1 board name, as found in the DIM server.
   const string ukl1Name = "pcukl101";
   //Register name needs to be the full DP name, hence requires the HW DP name prefix defined by this library.
   dyn_string registerNames;
   registerNames[1] = FWUKL1_HW_DP_NAME_PREFIX + ukl1Name + ".BeFpga.IpDestinationAddress"
   //Stores the read data.
   dyn_char readData;
   //Holds errors.
   dyn_int callStatusList;
   //Read and save the status.
   const bool readStatus = fwCcpc_read(registerNames, ddcData, callStatusList);
   //Check for errors...
   if (!readStatus)
     (...)

   fwUkl1_convert32To16BitWord(ddcData[1], exceptionInfo);
   if ( 0 != dynlen(exceptionInfo) )
     //...Handle errors, should be none if read successful...

   const string ipAddress = fwUkl1_convertByteToIp(ddcData[1], exceptionInfo);
   if ( 0 != dynlen(exceptionInfo) )
     //...Handle errors, should be none if read successful...
   DebugTN(ipAddress); //Colon delimited MAC address e.g. 192.168.255.0

   (...)

string fwUkl1_convertByteToMac const dyn_char &  macAddress,
dyn_string &  exceptionInfo
 

Takes an array of bytes and returns them as a colon delimited MAC address.

Parameters:
macAddress The array containing the bytes to be parsed.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
string Expects a 6 element array containing 3 elements with 16-bit words of data in each. Returns `Fail' if the input data is misformed.
This code requires that the extra bytes generated from a fwCcpc_read() are first removed, via fwUkl1_convert32To16BitWords(). Generally it is expected that this function will only be used internally and fwUkl1_parseBeFpgaReadRegisters() will be used if dealing with the BE FPGA registers. It is not defined an internal function as it mirrors the convert MAC to byte function, which is not internal.

Example

   (...)
   //Fictional UKL1 board name, as found in the DIM server.
   const string ukl1Name = "pcukl101";
   //Register name needs to be the full DP name, hence requires the HW DP name prefix defined by this library.
   dyn_string registerNames;
   registerNames[1] = FWUKL1_HW_DP_NAME_PREFIX + ukl1Name + ".BeFpga.MacDestinationAddress"
   //Stores the read data.
   dyn_char readData;
   //Holds errors.
   dyn_int callStatusList;
   //Read and save the status.
   const bool readStatus = fwCcpc_read(registerNames, ddcData, callStatusList);
   //Check for errors...
   if (!readStatus)
     (...)

   fwUkl1_convert32To16BitWord(ddcData[1], exceptionInfo);
   if ( 0 != dynlen(exceptionInfo) )
     //...Handle errors, should be none if read successful...

   const string macAddress = fwUkl1_convertByteToMac(ddcData[1], exceptionInfo);
   if ( 0 != dynlen(exceptionInfo) )
     //...Handle errors, should be none if read successful...
   DebugTN(macAddress); //Colon delimited MAC address e.g. 00:0E:0C:B0:2D:19

   (...)

string fwUkl1_convertIpToHex const string &  ipAddress,
dyn_string &  exceptionInfo
 

Takes a standard formed IP(4) address, as a string, and convert it to a continuous hex string. Also performs syntacs checking on the given string.

Parameters:
ipAddress The string that contains the IP address to be parsed. Should be of the form: XXX.XXX.XXX.XXX, where X represents a decimal number, e.g. 192.168.192.192. It is possible to miss the final byte i.e. 192.168.192, this is required for the source IP address. In this case where the final byte is missing it will be replaced with zeros in the resulting hex string.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
string If the IP address does not look like a IP address `Fail' will be returned, otherwise the hex string.
Expects the MAC address to be of the form 192.168.255.255 or 192.168.255 Example
   (...)
   //An IP address that we wish to convert.
   const string ipAddress1 = 192.168.255.1;
   //The equivalent hex string.
   const string hexAddress1 = fwUkl1_convertIpToHex(ipAddress1, exceptionInfo);
   if ( 0 != dynlen(exceptionInfo) )
     //...Will not have any error...
   DebugTN(hexAddress1);  //c0a8ff01

   //An IP address that we wish to convert.
   const string ipAddress2 = 192.168.255;
   //The equivalent hex string.
   const string hexAddress2 = fwUkl1_convertIpToHex(ipAddress1, exceptionInfo);
   if ( 0 != dynlen(exceptionInfo) )
     //...Will not have any error...
   DebugTN(hexAddress2);  //c0a8ff00, note the last byte are zeros.

   //Invalid IP address.
   const string ipAddress3 = 192.168.;
   const string hexAddress3 = fwUkl1_convertIpToHex(ipAddress2, exceptionInfo);
   if ( 0 != dynlen(exceptionInfo) )
     //...Handle error...
   DebugTN(hexAddress3);  //Fail
   (...)

string fwUkl1_convertMacToHex const string &  macAddress,
dyn_string &  exceptionInfo
 

Takes a colon delimited hex MAC address, as a string, and removes the colons to return a continuous hex string. It also performs checks on the data format.

Parameters:
macAddress The string that contains the MAC address to be parsed. Should be of the form XX:XX:XX:XX:XX:XX or XX:XX:XX:XX. The final two bytes can be omitted and should be for the source MAC address and then in the result hex MAC address they will be replaced with zeros in the resulting hex string.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
string MAC address without the colons. If the MAC address contains no colons it will be returned as it was. If the MAC address does not look like a MAC address `Fail' will be returned.
Expects the MAC address to be of the form 00:0e:0c:b0:2d:19 or 000e0cb02d19 i.e. 12 characters long. Example
   (...)
   //A colon delimited MAC address that we wish to convert.
   const string macAddress1 = 00:0e:0c:b0:2d:19;
   //A colonless MAC address.
   const string hexAddress1 = fwUkl1_convertMacToHex(macAddress1, exceptionInfo);
   if ( 0 != dynlen(exceptionInfo) )
     //...Will not have any error...
   DebugTN(hexAddress1);  //000e0cb02d19

   //A colon delimited MAC address that we wish to convert.
   const string macAddress2 = 00:0e:0c:b0;
   //A colonless MAC address.
   const string hexAddress2 = fwUkl1_convertMacToHex(macAddress1, exceptionInfo);
   if ( 0 != dynlen(exceptionInfo) )
     //...Will not have any error...
   DebugTN(hexAddress2);  //000e0cb00000

   //Invalid colon separated MAC address.
   const string macAddress3 = 00:0e:0c:b0:2d;
   const string hexAddress3 = fwUkl1_convertMacToHex(macAddress2, exceptionInfo);
   if ( 0 != dynlen(exceptionInfo) )
     //...Handle error...
   DebugTN(hexAddress3);  //Fail
   (...)

void fwUkl1_feFpgaChannelRead string  ukl1Name,
unsigned  channel,
unsigned  feFpga,
bool  readRecipe,
const string &  recipeName,
dyn_string  registerNames,
dyn_string &  data,
dyn_string &  exceptionInfo
 

This reads from a given set of registers on a FE FPGA channel. It can read from a single FE FPGA channel or all the channels on a FE FPGA in broadcast mode. The reads can either be from the hardware or they can be done from a configurationDB recipe. If reading from a recipe broadcast mode must be used.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
channel Input channel number on a FE FPGA that is to be written to. Range: 0 to 8, FWUKL1_BROADCAST_CHANNEL.
feFpga Number of the FE FPGA that is to be written. Range:0 to 3.
readRecipe If TRUE then the function will read the settings from the given recipe name and return the settings contained within. FALSE and the returned values will come directly from the hardware registers.
recipeName Name of the recipe to save the configuration information to if writeDb=TRUE, not used if writeDb=FALSE. The recipe must be of the form "RUN_TYPE/FsmAction", where RUN_TYPE is type of run that the recipe is to be loaded e.g PHYSICS, CALIBRATION, can take any value, but should be descriptive of the type of run the recipe settings represent; FsmAction is the action in the FSM when these settings should be loaded e.g. Configure if the recipe is to be used to moved to the READY state, typically only the first letter is upper case.
registerNames dyn_string that contains the name of the HwTypeCCPCUKL1 datapoint element to be read from, which corresponds to the appropriate hardware register.
data dyn_string returned by reference that contains a string representing the value in the register.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.

void fwUkl1_feFpgaChannelWrite string  ukl1Name,
unsigned  channel,
unsigned  feFpga,
bool  writeRecipe,
const dyn_string &  recipeNameAndType,
dyn_string  registerNames,
const dyn_string &  data,
bool  verifyWrite,
dyn_string &  exceptionInfo
 

This writes to a given set of registers on a FE FPGA channel. It can be used to write to either the registers on the UKL1 board or to a configurationDB recipe. If writing to a recipe broadcast mode must be used.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
channel Input channel number on a FE FPGA that is to be written to. Range: 0 to 8, FWUKL1_BROADCAST_CHANNEL.
feFpga Number of the FE FPGA that is to be written. Range:0 to 3.
writeRecipe If TRUE then the function will write the given register settings to the configurationDB recipe given by recipe name. FALSE it will write the register settings to the UKL1 board.
recipeNameAndType Two element array containing:
  • Element 1 - The name of the recipe to save the data to. It must be of the form "RUN_TYPE/FsmAction", where RUN_TYPE is descriptive of the type of run the settings are saved for e.g. PHYSICS, CALIBRATION; FsmAction is the action of FSM state transition where the recipe should be loaded e.g. Configure, the first letter only should be capitalised.
  • Element 2 - The second element contains the recipe type that it is to be saved to, this can be anything provided it already exists. This array is only required if writeRecipe=TRUE, otherwise it can be empty.
registerNames dyn_string that contains the name of the HwTypeCCPCUKL1 datapoint element to be written to, which corresponds to the appropriate hardware register. The accepted values are described in fwUkl1_parseFeFpgaChannelRegisters();
data By default a 16-bit value that is to be written to the register represented as a hex string, it need not be zero padded. Certain settings accept or require an alternative format as described in fwUkl1_parseFeFpgaChannelWriteRegisters() documentation.
verifyWrite If this is set to TRUE then the register will be read back from to ensure that the data written corresponds to that read. Default: FALSE.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.
If the recipe name does not exist it will be created. If the recipe type does not exist then the recipe may lose its type and all data associated with it. No checks are performed on the recipe type at present.

void fwUkl1_feFpgaRead string  ukl1Name,
unsigned  feFpga,
bool  readRecipe,
const string &  recipeName,
dyn_string  registerNames,
dyn_string &  data,
dyn_string &  exceptionInfo
 

This reads from a given set of registers on the FE FPGAs. It is capable of reading from either an individual FE FPGA or all FE FPGAs in broadcast mode. The source of the data can be either the UKL1 board or a recipe. If reading from a recipe the broadcast FPGA must be used.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
feFpga FE FPGA number that is to be written to. Range: 0 to 3, FWUKL1_BROADCAST_FPGA.
readRecipe If TRUE then the function will read the settings from the given recipe name and return the settings contained within. FALSE and the returned values will come directly from the hardware registers.
recipeName Name of the recipe to save the configuration information to if writeDb=TRUE, not used if writeDb=FALSE. The recipe must be of the form "RUN_TYPE/FsmAction", where RUN_TYPE is type of run that the recipe is to be loaded e.g PHYSICS, CALIBRATION, can take any value, but should be descriptive of the type of run the recipe settings represent; FsmAction is the action in the FSM when these settings should be loaded e.g. Configure if the recipe is to be used to moved to the READY state, typically only the first letter is upper case.
registerNames dyn_string that contains the name of the HwTypeCCPCUKL1 datapoint element to be read from, which corresponds to the appropriate hardware register.
data dyn_string returned by reference that contains a string representing the value in the register.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void

void fwUkl1_feFpgaWrite string  ukl1Name,
unsigned  feFpga,
bool  writeRecipe,
const dyn_string &  recipeNameAndType,
dyn_string  registerNames,
const dyn_string &  data,
bool  verifyWrite,
dyn_string &  exceptionInfo
 

Writes to a given set of UKL1 registers. Data should be in a form acceptable to the fwUkl1_parseFeFpgaWriteRegisters() as it will first be passed through this function before being written to the hardware.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
feFpga Number of the FE FPGA that is to be written. Range:0 to 3, FWUKL1_BROADCAST_FPGA. FWUKL1_BROADCAST_FPGA is a software creatation that allows all the FE FPGAs to be written to in a single command. It saves on the number of hardware accesses by a factor of four.
writeRecipe If TRUE then the function will write the given register settings to the configurationDB recipe given by recipe name. FALSE it will write the register settings to the UKL1 board.
recipeNameAndType Two element array containing:
  • Element 1 - The name of the recipe to save the data to. It must be of the form "RUN_TYPE/FsmAction", where RUN_TYPE is descriptive of the type of run the settings are saved for e.g. PHYSICS, CALIBRATION; FsmAction is the action of FSM state transition where the recipe should be loaded e.g. Configure, the first letter only should be capitalised.
  • Element 2 - The second element contains the recipe type that it is to be saved to, this can be anything provided it already exists. This array is only required if writeRecipe=TRUE, otherwise it can be empty.
registerNames dyn_string containing the names of the registers that need to be read. It need not contain the full path of the register i.e. the datapoint name and hardware chip (BeFpga, GBE) must be neglected. Care must be taken that the registers requested exist.
data By default a 16-bit value that is to be written to the register represented as a hex string, it need not be zero padded. Certain settings accept or require an alternative format as described in fwUkl1_parseFeFpgaRegisters. For a single FPGA write the data should be in the format above with one element for each register. If broadcasting then the data must be comma delimited and four values MUST be present e.g. To disable a single front end `Enable,Enable,Disable,Enable'.
verifyWrite If this is set to TRUE then the register will be read back from to ensure that the data written corresponds to that read. Default: FALSE.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.
If the recipe name does not exist it will be created. If the recipe type does not exist then the recipe may lose its type and all data associated with it. No checks are performed on the recipe type at present.

void fwUkl1_gbePortRead string  ukl1Name,
unsigned  port,
bool  readRecipe,
const string &  recipeName,
dyn_string  registerNames,
dyn_string &  data,
dyn_string &  exceptionInfo
 

This reads from a given set of GBE port registers. The reads can either be from the hardware or they can be done from a configurationDB recipe.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
port Output port on the GBE card that is to be set.
readRecipe If TRUE then the function will read the settings from the given recipe name and return the settings contained within. FALSE and the returned values will come directly from the hardware registers.
recipeName Name of the recipe to save the configuration information to if writeDb=TRUE, not used if writeDb=FALSE. The recipe must be of the form "RUN_TYPE/FsmAction", where RUN_TYPE is type of run that the recipe is to be loaded e.g PHYSICS, CALIBRATION, can take any value, but should be descriptive of the type of run the recipe settings represent; FsmAction is the action in the FSM when these settings should be loaded e.g. Configure if the recipe is to be used to moved to the READY state, typically only the first letter is upper case.
registerNames dyn_string that contains the name of the HwTypeCCPCUKL1 datapoint element to be read from, which corresponds to the appropriate hardware register.
data dyn_string returned by reference that contains a string representing the value in the register. It will be zero padded to the nearest 32-bit word.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.

void fwUkl1_gbePortWrite string  ukl1Name,
unsigned  port,
bool  writeRecipe,
const dyn_string &  recipeNameAndType,
dyn_string  registerNames,
dyn_string  data,
bool  verifyWrite,
dyn_string &  exceptionInfo
 

This writes to a given set of registers on a GBE port. It can be used to write to either the registers on the UKL1 board or to a configurationDB recipe.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
port Output port on the GBE card that is to be set.
writeRecipe If TRUE then the function will write the given register settings to the configurationDB recipe given by recipe name. FALSE it will write the register settings to the UKL1 board.
recipeNameAndType Two element array containing:
  • Element 1 - The name of the recipe to save the data to. It must be of the form "RUN_TYPE/FsmAction", where RUN_TYPE is descriptive of the type of run the settings are saved for e.g. PHYSICS, CALIBRATION; FsmAction is the action of FSM state transition where the recipe should be loaded e.g. Configure, the first letter only should be capitalised.
  • Element 2 - The second element contains the recipe type that it is to be saved to, this can be anything provided it already exists. This array is only required if writeRecipe=TRUE, otherwise it can be empty.
registerNames dyn_string that contains the name of the HwTypeCCPCUKL1 datapoint element to be written to, which corresponds to the appropriate hardware register. The accepted values are described in fwUkl1_parseGbeWriteRegisters();
data By default a 32-bit value that is to be written to the register represented as a hex string, it need not be zero padded. Certain settings accept or require an alternative format as described for each register above.
verifyWrite If this is set to TRUE then the register will be read back from to ensure that the data written corresponds to that read. Default: FALSE.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.

void fwUkl1_gbeRead string  ukl1Name,
bool  readRecipe,
const string &  recipeName,
dyn_string  registerNames,
dyn_string &  data,
dyn_string &  exceptionInfo
 

This reads from a given set of general GBE registers. The reads can either be from the hardware or they can be done from a configurationDB recipe.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
readRecipe If TRUE then the function will read the settings from the given recipe name and return the settings contained within. FALSE and the returned values will come directly from the hardware registers.
recipeName Name of the recipe to save the configuration information to if writeDb=TRUE, not used if writeDb=FALSE. The recipe must be of the form "RUN_TYPE/FsmAction", where RUN_TYPE is type of run that the recipe is to be loaded e.g PHYSICS, CALIBRATION, can take any value, but should be descriptive of the type of run the recipe settings represent; FsmAction is the action in the FSM when these settings should be loaded e.g. Configure if the recipe is to be used to moved to the READY state, typically only the first letter is upper case.
registerNames dyn_string that contains the name of the HwTypeCCPCUKL1 datapoint element to be read from, which corresponds to the appropriate hardware register.
data dyn_string returned by reference that contains a string representing the value in the register. It will be zero padded to the nearest 32-bit word.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.

void fwUkl1_gbeWrite string  ukl1Name,
bool  writeRecipe,
const dyn_string &  recipeNameAndType,
dyn_string  registerNames,
const dyn_string &  data,
bool  verifyWrite,
dyn_string &  exceptionInfo
 

This writes to a given set of registers on the giga-bit ethernet (GBE) card. It can be used to write to either the registers on the UKL1 board or to a configurationDB recipe.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
writeRecipe If TRUE then the function will write the given register settings to the configurationDB recipe given by recipe name. FALSE it will write the register settings to the UKL1 board.
recipeNameAndType Two element array containing:
  • Element 1 - The name of the recipe to save the data to. It must be of the form "RUN_TYPE/FsmAction", where RUN_TYPE is descriptive of the type of run the settings are saved for e.g. PHYSICS, CALIBRATION; FsmAction is the action of FSM state transition where the recipe should be loaded e.g. Configure, the first letter only should be capitalised.
  • Element 2 - The second element contains the recipe type that it is to be saved to, this can be anything provided it already exists. This array is only required if writeRecipe=TRUE, otherwise it can be empty.
registerNames dyn_string that contains the name of the HwTypeCCPCUKL1 datapoint element to be written to, which corresponds to the appropriate hardware register. The accepted values are described in fwUkl1_parseGbeWriteRegisters();
data By default a 32-bit value that is to be written to the register represented as a hex string, it need not be zero padded. Certain settings accept or require an alternative format as described in fwUkl1_parseGbeWriteRegisters() documentation.
verifyWrite If this is set to TRUE then the register will be read back from to ensure that the data written corresponds to that read. Default: FALSE.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.

string fwUkl1_getUkl1SerialNumber const string &  ukl1Name,
dyn_string &  exceptionInfo
 

A function to read the serial number from a UKl1 board.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
string Contain the 32-bit serial number as a single hex string. The string will return `Fail' if it does not succeed. The read string is byte swapped and it will be converted to the appropriate byte order. If this cannot be done the original byte ordered string is returned if possible and this is noted in exceptionInfo.

dyn_int fwUkl1_getUkl1Temperatures string  ukl1Name,
dyn_string &  exceptionInfo
 

This function allows the temperature probes to be read.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
dyn_int Temperatures read from the temperature sensors around the UKL1 board. The return elements are as follows:
  • 0 Top of the board near Ingress FPGA 0, sensor on lowest register address.
  • 1 Middle of the board, sensor on middle register address.
  • 2 Bottom of the board near Ingress FPGA 3, sensor on highest address. -1 will be returned if there is an error, which will be described in exceptionInfo.

void fwUkl1_padString string &  sData,
unsigned  numBytes
 

Takes a string and ensures that it contains enough characters for the number of bytes specified by numBytes. Adds `0' to the beginnig if it is too short and removes characters from the beginning if it is too long. Must be in hex.

Parameters:
sData The string that contains the data to be checked. Returned by reference.
numBytes The number of bytes that the returned character string should return.
Returns:
void
This is for use with strings that represent a hex number that should be a set number of bits long. It assumes that the lowest order bit is the last (reading left to right) character and hence its behaviour is to move the last character always towards the final character in the padded string (the 2nd, 4th, 6th etc character). This is achieved by padding or removing at the beginning of the string.

Example:

   (...)
   //Declare some data e.g. User input from a panel.
   const string hexData1 = "1234";
   //Wish to use the fwCcpc library to write this to a 32-bit registers hence is needs to be zero padded
   //to be 4-bytes big (8-characters).
   const string paddedData1 = fwUkl1_padString(hexData1, 4);
   DebugTN(paddedData1); // "00001234"

   //Declare some more data e.g. User input from a panel.
   const string hexData2 = "1234";
   //Wish to use the fwCcpc library to write this to an 8-bit registers hence it need to be 1-byte (2-characters) big.
   const string paddedData2 = fwUkl1_padString(hexData2, 1);
   //Here the data is misformed and it is assumed that the least significant bit (last character) in the given number
   //should remain the least significant bit.
   DebugTN(paddedData2); // "34"
   (...)

void fwUkl1_parseBeFpgaReadRegisters string  ukl1Name,
const dyn_string &  registerNames,
dyn_dyn_char  ddcData,
dyn_string &  data,
const dyn_int &  callStatusList,
dyn_string &  exceptionInfo
 

Takes the data read from the BE FPGA configuration registers using fwCcpc_read or from a recipe and converts them to strings to provide a description of the register setting. It also splits settings that occupy the same register address into their own description.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
registerNames dyn_string that contains the names and the BE FPGA registers to be read from as named in the UKL1 hardware datapoint. They can either be the full name or just the register name. The following registers can be parsed (their names are given in the short form, just the DP element) and also a description of the return value given by sData:
  • MacDestinationAddress A 12 character string that gives the hex number for the MAC address, can either be a continuous string of the address or may posses a colon delimiter every two characters, e.g. 000e0cb02d19 or 00:0e:0c:b0:2d:19.
  • MacSourceAddress A 12 character string that gives the hex number for the MAC address, can either be a continuous string of the address or may posses a colon delimiter every two characters, e.g. 000e0cb02d19 or 00:0e:0c:b0:2d:19.
  • IpDestinationAddress A string that contains either the address in hex format e.g. c0a0c0c0 or in a typical IP4 format e.g. 192.168.192.192.
  • IpSourceAddress A string that contains either the address in hex format e.g. c0a0c0c0 or in a typical IP4 format e.g. 192.168.192.192.
  • Protocol Default format described below.
  • TypeOfService Default format described below.
  • TimeToLive Default format described below.
  • Type Default format described below.
  • Version Default format described below.
  • PartitionId Must contain an 8 character string representing the two 16-bit words of data for the partition ID.
  • L1Id An 8-bit value, 2-character string. This will be present in the output data packet and MUST be unique for each L1. This is set correctly by the FSM and generally should not be User defined, except maybe when the User is an expert.
  • ZeroSuppression String should be either `Enable' or `Disable' to enable or disable zero suppression across all the Ingress/FE FPGAs. Case sensitive.
  • HpdPixelMode String should be either `ALICE' or `LHCb', which should correspond to the mode of operation required from the pixel chips. Case sensitive.
  • Latency Default format described below.
  • MepPackingFactor Default format described below.
  • FixedMepDestinationAddress `Enable' or `Disable' to enable or disable a fixed multi-event packet destination address.
  • DontWaitForMepDestBrdcst `Don't wait' or `Wait' to enable or disable the waiting for a multi-event packet destination address broadcast, respectively.
  • Throttle `Enable' or `Disable' to enable or disable the throttle.
  • ThrottlePolarity `Invert' or `Normal' to select the polarity of the throttle output.
  • TfcDecoder `Enable' or `Disable' to enable or disable the decoding of TFC commands. The board will not operate without this setting enabled.
  • PollGbePorts `Enable' or `Disable' to enable the Egress FPGA to send data to the GBE card for transmission.
  • DataFragmentSize A decimal number specifying the size of the data packet that is transmitted via the GBE card. It is the size of the fragment of the multi-event packet that is transmitted. Max 9000.
  • MepTruncationHighWtrmrk Decimal number, max 65355, that represents the number of 32-bit words that can be put into a MEP before it is truncated.
ddcData This contains the raw data that has been read back from the PVSS datapoint.
data dyn_string returned by reference that contains a string representing the value in the register. It will either be a hex representation, zero padded to the nearest byte boundary or a text description of the settings. In the event that the read failed it will contain the text `Fail'.
callStatusList This is the status list returned by the fwCcpc_read function and if the data to be parsed was generated by the use of this function then a callStatusList should be passed in order that errors can be checked for. It is possible, for example via monitoring, that the fwCcpc_read function is not used and in this case an empty array should be passed and it will be ignored. Any errors found in this array will be reported via the exceptionInfo.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void
It does not matter if data is being parsed from a recipe or from the hardware the results are the same. The recipe data must first be converted from a string to a dyn_char (can be achieved through fwCcpc_convertHexToByte()).

void fwUkl1_parseBeFpgaWriteRegisters string  ukl1Name,
dyn_string &  registerNames,
dyn_string  sData,
dyn_dyn_char &  ddcData,
dyn_dyn_char &  masks,
dyn_string &  exceptionInfo
 

This function takes the data for the various BE FPGA registers described by a string and converts it to data that can used with fwCcpc_write() or fwHw_saveRecipe(). It allows data to be given in a more human readable format and converts it to the byte array required for writting to the CCPC. It also returns the appropriate mask that must be used when writing the data. If being used with fwHw_saveRecipe() then the mask will have to be appended to the data array.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
registerNames dyn_string that contains the name of the HwTypeCCPCUKL1 datapoint element to be written to, which corresponds to the appropriate hardware register. The appropriate name prefix is added and returned by reference. The following values are permitted:
  • MacDestinationAddress A 12 character string that gives the hex number for the MAC address, can either be a continuous string of the address or it may posses a colon delimiter every two characters, e.g. 000e0cb02d19 or 00:0e:0c:b0:2d:19.
  • MacSourceAddress An eight character string that gives the first 4 bytes of the MAC address. The remaining bytes are not User configurable and are set during a fwUkl1_configure(). There are two possible forms either a continuous string of the address or it may posses a colon delimiter every two characters, e.g. 000e0cb0 or 00:0e:0c:b0.
  • IpDestinationAddress A string that contains either the address in hex format e.g. c0a0c0c0 or in a typical IP4 format e.g. 192.168.192.192.
  • IpSourceAddress A string that contains either the first three bytes of the address (reading left to right) in hex format e.g. c0a0c0 or in a typical IP4 format e.g. 192.168.192 . The remaining byte is not User configurable and set during fwUkl1_configure().
  • Protocol Default format described below.
  • TypeOfService Default format described below.
  • TimeToLive Default format described below.
  • Type Default format described below.
  • Version Default format described below.
  • PartitionId Must contain an 8 character string representing the two 16-bit words of data for the partition ID.
  • L1Id An 8-bit value, 2-character string. This will be present in the output data packet and MUST be unique for each L1. This is set correctly by the FSM and generally should not be User defined, except maybe when the User is an expert.
  • ZeroSuppression String should be either `Enable' or `Disable' to enable or disable zero suppression across all the Ingress/FE FPGAs. Case sensitive.
  • HpdPixelMode String should be either `ALICE' or `LHCb', which should correspond to the mode of operation required from the pixel chips. Case sensitive.
  • Latency Default format described below.
  • MepPackingFactor Default format described below.
  • FixedMepDestinationAddress `Enable' or `Disable' to enable or disable a fixed multi-event packet destination address.
  • DontWaitForMepDestBrdcst `Don't wait' or `Wait' to enable or disable the waiting for a multi-event packet destination address broadcast, respectively.
  • Throttle `Enable' or `Disable' to enable or disable the throttle.
  • ThrottlePolarity `Invert' or `Normal' to select the polarity of the throttle output.
  • TfcDecoder `Enable' or `Disable' to enable or disable the decoding of TFC commands. The board will not operate without this setting enabled.
  • PollGbePorts `Enable' or `Disable' to enable the Egress FPGA to send data to the GBE card for transmission.
  • DataFragmentSize A decimal number specifying the size of the data packet that is transmitted via the GBE card. It is the size of the fragment of the multi-event packet that is transmitted. Max 9000.
  • MepTruncationHighWtrmrk Decimal number, max 65355, that represents the number of 32-bit words that can be put into a MEP before it is truncated.
sData Data to be written to the registers in the form of a string. The default format to be used is a hex string, lower or upper case that need not be zero padded to the appropriate register size.
ddcData Data converted into a dyn_dyn_char for use with the fwCcpc_write function. Returned by reference.
masks Masks that are associated with the write data also to be used with the fwCcpc_write function.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void
Improperly formatted data will be removed from the list of write registers and will be indicated by an increased size of the exceptionInfo array. The returned ddcData is not quite suitable for writting to the database and the masks must first be appeneded to the end of element in the ddcData, this must be done by the User.

dyn_dyn_string fwUkl1_parseBroadcastData const dyn_string &  origData,
dyn_string &  exceptionInfo
 

This takes a array of string where each element of the array contains the relevant settings for either the FE FPGAs, the channels on a FE FPGA or the GBE ports and converts these to an array of strings. The returned result is an array of array of strings that contain all the relevant settings.

Parameters:
origData The dyn_string that contains the data to be parsed. Each element should contain a comma separated list of settings.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
dyn_dyn_string Each element contains a dyn_string, where each element contains the setting for an individual unit. In the event of an empty input an empty dyn_dyn_string is returned and this is signalled via exceptionInfo. In the event there is no comma delimited or it could not be parsed an empty dyn_string is returned for the corresponding element in the returned dyn_dyn_string. As it is not possible to know how many elements the User was expecting from the parsed data it is not possible to populate the array with a sensible amount of empty strings hence the size of the returned dyn_string in each element of the returned dyn_dyn_string must be checked. It is gaurantied in that if no exceptionInfo is generated by this function the returned dyn_dyn_string will contain at least an empty dyn_string for each element of the input data.
The input strings must contain a comma separated list of the unit settings. The function checks that there are either four or nine settings found, if there are none then the data format is considered to be invalid and for that specific element an empty string is return. It will continue to parse the rest of the data if an error is found. The ordering of the output data is the first element in the array corresponds to the first entry in the string reading left to right.

void fwUkl1_parseFeFpgaChannelReadRegisters string  ukl1Name,
unsigned  channel,
unsigned  feFpga,
const dyn_string &  registerNames,
dyn_dyn_char  ddcData,
dyn_string &  data,
const dyn_int &  callStatusList,
dyn_string &  exceptionInfo
 

Takes the data read from the FE FPGA channel configuration registers using fwCcpc_read or from a recipe and converts them to string to provide a description of the register setting. It also splits settings that occupy the same register address into their own description.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
channel Input channel number on a FE FPGA that is to be written to. Range: 0 to 8, FWUKL1_BROADCAST_CHANNEL.
feFpga Number of the FE FPGA that is to be written. Range:0 to 3.
registerNames dyn_string that contains the names and the FE FPGA registers to be read from as named in the UKL1 hardware datapoint. They can either be the full name or just the register name. The following registers can be parsed (their names are given in the short form, just the DP element) and also a description of the return value given by sData: It will be zero padded to the nearest 16-bit word, except in the following cases:
  • Disable `Enable' or `Disable' depending on the state of the channel. In the event that a broadcast is issued the return data will be comma separated.
ddcData This contains the raw data that has been read back from the PVSS datapoint.
data dyn_string returned by reference that contains a string representing the value in the register. It will either be a hex representation, zero padded to the nearest byte boundary or a text description of the settings. In the event that the read failed it will contain the text `Fail'.
callStatusList This is the status list returned by the fwCcpc_read function and if the data to be parsed was generated by the use of this function then a callStatusList should be passed in order that errors can be checked for. It is possible, for example via monitoring, that the fwCcpc_read function is not used and in this case an empty array should be passed and it will be ignored. Any errors found in this array will be reported via the exceptionInfo.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.

void fwUkl1_parseFeFpgaChannelWriteRegisters string  ukl1Name,
unsigned  channel,
unsigned  feFpga,
dyn_string &  registerNames,
dyn_string  sData,
dyn_dyn_char &  ddcData,
dyn_dyn_char &  masks,
dyn_string &  exceptionInfo
 

This function takes the data for the various FE FPGA channel registers described by a string and converts it to data that can used with fwCcpc_write() or fwHw_saveRecipe(). It allows data to be given in a more human readable format and converts it to the byte array required for writting to the CCPC. It also returns the appropriate mask that must be used when writing the data. If being used with fwHw_saveRecipe() then the mask will have to be appended to the data array.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
channel Input channel number on a FE FPGA that is to be written to. Range: 0 to 8, FWUKL1_BROADCAST_CHANNEL.
feFpga Number of the FE FPGA that is to be written. Range:0 to 3.
registerNames List of FE FPGA channel register names that are to be written to. Returned with the appropriate name prefix by reference. The allowed values are:
  • Disable Accepts the text `Disable' or `Enable' to disable or enable a FE FPGA.
sData Data to be written to the registers in the form of a hex string. The default value is a 4-character hex string, other values are accepted for specific registers as described above.
ddcData Data converted into a dyn_dyn_char for use with the fwCcpc_write function. Returned by reference.
masks Masks that are associated with the write data.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.
Improperly formatted data will be removed from the list of write registers and will be indicated by an increased size of the exceptionInfo array.

void fwUkl1_parseFeFpgaReadRegisters string  ukl1Name,
unsigned  feFpga,
const dyn_string &  registerNames,
dyn_dyn_char  ddcData,
dyn_string &  data,
const dyn_int &  callStatusList,
dyn_string &  exceptionInfo
 

Takes the data read from the FE FPGA configuration registers using fwCcpc_read or a recipe and converts them to string to provide a description of the register setting. It also splits settings that occupy the same register address into their own description.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
feFpga Number of the FE FPGA that is to be written. Range:0 to 3, FWUKL1_BROADCAST_FPGA.
registerNames dyn_string that contains the names and the FE FPGA registers to be read from as named in the UKL1 hardware datapoint. They can either be the full name or just the register name. The following registers can be parsed (their names are given in the short form, just the DP element) and also a description of the return value given by sData: It will be zero padded to the nearest 16-bit word, except in the following cases:
  • Disable `Enable' or `Disable' depending on the state of the FPGA.
  • Emulator `Disable' or `Enable' depending on whether the L0 emulation is active or not.
  • EmulatorHpdPixelMode `LHCb' or `ALICE' depending on which HPD pixel mode is being simulated in the events.
  • EmulatorEvent `Send' or `Don't send' depending on whether or not events are being sent when in L0 emulation mode.
  • ResetStatusBufferPointer `Assert' or `Deassert' depending on whether the reset is asserted or not. In broadcast mode the returned data elements will contain a comma delimited list of the settings for each individual FE FPGA.
ddcData This contains the raw data that has been read back from the PVSS datapoint.
data dyn_string returned by reference that contains a string representing the value in the register. It will either be a hex representation, zero padded to the nearest byte boundary or a text description of the settings. In the event that the read failed it will contain the text `Fail'.
callStatusList This is the status list returned by the fwCcpc_read function and if the data to be parsed was generated by the use of this function then a callStatusList should be passed in order that errors can be checked for. It is possible, for example via monitoring, that the fwCcpc_read function is not used and in this case an empty array should be passed and it will be ignored. Any errors found in this array will be reported via the exceptionInfo.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.

void fwUkl1_parseFeFpgaWriteRegisters string  ukl1Name,
unsigned  feFpga,
dyn_string &  registerNames,
dyn_string  sData,
dyn_dyn_char &  ddcData,
dyn_dyn_char &  masks,
dyn_string &  exceptionInfo
 

This function takes the data for the various FE FPGA registers described by a string and converts it to data that can used with fwCcpc_write() or fwHw_saveRecipe(). It allows data to be given in a more human readable format and converts it to the byte array required for writting to the CCPC. It also returns the appropriate mask that must be used when writing the data. If being used with fwHw_saveRecipe() then the mask will have to be appended to the data array.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
feFpga Number of the FE FPGA that is to be written. Range:0 to 3, FWUKL1_BROADCAST_FPGA.
registerNames List of FE FPGA register names that are to be written to. Returned with the appropriate name prefix by reference. The allowed values are described below.
  • Disable Accepts the text `Disable' or `Enable' to disable or enable a FE FPGA.
  • Emulator Accepts the text `Disable' or `Enable' to disable or enable input data emulation on that FE FPGA, respectively. This setting disables the input data from the optical inputs on the 9 associated inputs channels and then sends emulated data through the L1 data processing chain.
  • EmulatorHpdPixelMode Accepts `LHCb' or `ALICE'. The type of emulated data that will be sent. This will not automatically enable the event emulation.
  • EmulatorEvent Accepts `Send' or `Don't send' to enable the sending of emulated events. This can only occur if the emulator is enabled via the `Emulator' setting. `Don't send' will prevent events being sent through the chain even if the emulator is enabled.
  • ResetStatusBufferPointer Accepts `Assert' or `Deassert', which will either assert or deassert the reset for the buffer pointer for that FE FPGA. This must be done before reading the status information for a FE FPGA or it will produce undefined data.
sData Data to be written to the registers in the form of a string. The default case is a 4-character hex string, comma separated in the case of broadcast data.
ddcData Data converted into a dyn_dyn_char for use with the fwCcpc_write function. Returned by reference.
masks Masks that are associated with the write data.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.
Improperly formatted data will be removed from the list of write registers and will be indicated by an increased size of the exceptionInfo array.

void fwUkl1_parseGbePortReadRegisters string  ukl1Name,
unsigned  port,
const dyn_string &  registerNames,
dyn_dyn_char  ddcData,
dyn_string &  data,
const dyn_int &  callStatusList,
dyn_string &  exceptionInfo
 

This takes the data read from the GBE port registers in the format as read from fwCcpc_read() or fwHw_getRecipe() and returns the values as a decriptive string.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
port Output port on the GBE card that is to be set.
registerNames dyn_string that contains the name of the HwTypeCCPCUKL1 datapoint elements to be read from, which corresponds to the appropriate hardware register. The accepted names are:
  • Duplex Default data format, see below.
  • MAC Default data format, see below.
  • Config Default data format, see below.
  • TXFifoThreshold Decimal number.
  • TXFifoLowWtrmrk Decimal number.
  • TXFifoHighWtrmrk Decimal number.
  • PHYControl Default data format, see below.
  • PHYStatus Default data format, see below.
  • TXStat Default data format, see below.
  • RXStat Default data format, see below.
ddcData This contains the raw data that has been read back from the PVSS datapoint.
data dyn_string returned by reference that contains a string representing the value in the register. It will either be a hex representation, zero padded to the nearest byte boundary or a text description of the settings. In the event that the read failed it will contain the text `Fail'.
callStatusList This is the status list returned by the fwCcpc_read function and if the data to be parsed was generated by the use of this function then a callStatusList should be passed in order that errors can be checked for. It is possible, for example via monitoring or reading from a recipe, that the fwCcpc_read function is not used and in this case an empty array should be passed and it will be ignored. Any errors found in this array will be reported via the exceptionInfo.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.

void fwUkl1_parseGbePortWriteRegisters string  ukl1Name,
unsigned  port,
dyn_string &  registerNames,
dyn_string  sData,
dyn_dyn_char &  ddcData,
dyn_dyn_char &  masks,
dyn_string &  exceptionInfo
 

This function takes the data for the various GBE registers described by a string and converts it to data that can used with fwCcpc_write() or fwHw_saveRecipe(). It allows data to be given in a more human readable format and converts it to the byte array required for writting to the CCPC. It also returns the appropriate mask that must be used when writing the data. If being used with fwHw_saveRecipe() then the mask will have to be appended to the data array.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
port Output port on the GBE card that is to be set.
registerNames List of GBE register names that are to be written to. Returned with the appropriate name prefix by reference. The allowed values are:
  • Duplex Default data format, see below.
  • MAC Default data format, see below.
  • Config Default data format, see below.
  • TXFifoThreshold Decimal number.
  • TXFifoLowWtrmrk Decimal number.
  • TXFifoHighWtrmrk Decimal number.
  • PHYControl Default data format, see below.
  • PHYStatus Default data format, see below.
  • TXStat Default data format, see below.
  • RXStat Default data format, see below.
sData Data to be written to the registers in the form of a hex string. The default value is an 8-character hex string, other values are accepted for specific registers as described above.
ddcData sData converted into a dyn_dyn_char for use with the fwCcpc_write function. Returned by reference.
masks Masks that are associated with the write data.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.
Improperly formatted data will be removed from the list of write registers and will be indicated by an increased size of the exceptionInfo array.

void fwUkl1_parseGbeReadRegisters string  ukl1Name,
const dyn_string &  registerNames,
dyn_dyn_char  ddcData,
dyn_string &  data,
const dyn_int &  callStatusList,
dyn_string &  exceptionInfo
 

This takes the data read from the GBE registers in the format as read from fwCcpc_read() or fwHw_getRecipe() and returns the values as a decriptive string.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
registerNames dyn_string that contains the name of the HwTypeCCPCUKL1 datapoint elements to be read from, which corresponds to the appropriate hardware register. The accepted names are:
  • JTAGID Default data format, see below.
  • MACSoftReset Default data format, see below.
  • RxFifoPrtReset Default data format, see below.
  • TxFifoPrtReset Default data format, see below.
  • PortEnable `Enable' or `Disable' in a comma delimited format. Values for all four ports must be present.
  • RxFifoEnable Default data format, see below.
  • Mode Default data format, see below.
  • Clock Default data format, see below.
  • SPI3ConfigTrnmtGlobal Default data format, see below.
  • SPI3ConfigRcv Default data format, see below.
  • RxStatus Default data format, see below.
  • PHYCtrl Default data format, see below.
  • PHYData Default data format, see below.
  • MDIOControl Default data format, see below.
ddcData This contains the raw data that has been read back from the PVSS datapoint.
data dyn_string returned by reference that contains a string representing the value in the register. It will either be a hex representation, zero padded to the nearest byte boundary or a text description of the settings. In the event that the read failed it will contain the text `Fail'.
callStatusList This is the status list returned by the fwCcpc_read function and if the data to be parsed was generated by the use of this function then a callStatusList should be passed in order that errors can be checked for. It is possible, for example via monitoring or reading from a recipe, that the fwCcpc_read function is not used and in this case an empty array should be passed and it will be ignored. Any errors found in this array will be reported via the exceptionInfo.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.

void fwUkl1_parseGbeWriteRegisters string  ukl1Name,
dyn_string &  registerNames,
dyn_string  sData,
dyn_dyn_char &  ddcData,
dyn_dyn_char &  masks,
dyn_string &  exceptionInfo
 

This function takes the data for the various GBE registers described by a string and converts it to data that can used with fwCcpc_write() or fwHw_saveRecipe(). It allows data to be given in a more human readable format and converts it to the byte array required for writting to the CCPC. It also returns the appropriate mask that must be used when writing the data. If being used with fwHw_saveRecipe() then the mask will have to be appended to the data array.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
registerNames List of GBE register names that are to be written to. Returned with the appropriate name prefix by reference. The allowed values are:
  • JTAGID Default data format, see below.
  • MACSoftReset Default data format, see below.
  • RxFifoPrtReset Default data format, see below.
  • TxFifoPrtReset Default data format, see below.
  • PortEnable `Enable' or `Disable' in a comma delimited format. Values for all four ports must be present.
  • RxFifoEnable Default data format, see below.
  • Mode Default data format, see below.
  • Clock Default data format, see below.
  • SPI3ConfigTrnmtGlobal Default data format, see below.
  • SPI3ConfigRcv Default data format, see below.
  • RxStatus Default data format, see below.
  • PHYCtrl Default data format, see below.
  • PHYData Default data format, see below.
  • MDIOControl Default data format, see below.
sData Data to be written to the registers in the form of a hex string. The default value is an 8-character hex string, other values are accepted for specific registers as described above.
ddcData sData converted into a dyn_dyn_char for use with the fwCcpc_write or fwHw_saveRecipe function. Returned by reference.
masks Masks that are associated with the write data.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.
Improperly formatted data will be removed from the list of write registers and will be indicated by an increased size of the exceptionInfo array.

int fwUkl1_parseReadRegister dyn_char  dcData,
unsigned  startBit,
unsigned  length,
bool  fpga,
dyn_string &  exceptionInfo
 

The purpose of this function is to take the data read from the UKL1 registers and to allow a specific group of continuous bits to be returned as a integer. The function poses the ability to deal with registers of any size e.g. the 32-bit registers from the GBE or FPGAs, or the 8-bit registers from the I2C. It is also capable of dealing with the format of the FPGA registers as read from the UKL1s and a boolean switch it used to indicate that these must be handled. Typically this will be used with monitored registers.

Parameters:
dcData Data read from the register as a byte array.
startBit Number of the first bit to be read from the register, where bit 0 is the least significant bit.
length Number of bits to be read, set to 1 if only startBit is to be read. Maximum 32.
fpga Boolean value to indicate whether we are parsing FPGA registers or not. This must be set correctly otherwise the data will not be properly interpreted.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
int Unsigned integer representation of the bits if the function is successful or -1 if it fails.
The reason for the FPGA flag is that the UKL1 FPGA registers are read as if they were 32-bit registers and not the 16-bit registers that they are physically (this is because sequential addresses are 32-bits apart and not 16!). This function will remove the extra two junk words that are read and parse only the remaining data in this case. Do not remove these extra words manually before hand. This function can return sections that are a maximum of 32-bits in length. The only registers that are bigger than this are the MAC addresses and these have their own dedicated convertion functions. The input size of the register is unlimited.

Example:

  (...)
  //Fictional UKL1 board name, as found in the DIM server.
  const string ukl1Name = "pcukl101";
  //Register name needs to be the full DP name, hence requires the HW DP name prefix defined by this library.
  dyn_string registerNames;
  registerNames[1] = FWUKL1_HW_DP_NAME_PREFIX + ukl1Name + ".BeFpga.ZeroSuppression"
  //Stores the read data.
  dyn_char readData;
  //Holds errors.
  dyn_int callStatusList;
  //Read and save the status.
  const bool readStatus = fwCcpc_read(registerNames, ddcData, callStatusList);
  //Check for errors...
  if (!readStatus)
    (...)

  //Data read from the zero suppression register contains also the HPD pixel mode data which we are not interested in,
  //hence this function will return only the zero suppression data.
  //Zero suppression data spans 4 bits, starting with the least significant bit.
  const unsigned startBit = 0;
  const unsigned length   = 4;
  //The zero suppression setting is on a FPGA register.
  const bool fpga = TRUE;
  //Check for errors.
  dyn_string exceptionInfo;
  //Convert the data.
  const int zeroSuppData = fwUkl1_parseReadRegister(ddcData[1], startBit, length, fpga, exceptionInfo);
  //Check for errors.
  if ( 0 < dynlen(exceptionInfo) )
    (...)

  //If zero suppression is enabled then 0xf would be returned.
  if ( 0xf == zeroSuppData )
    (...zero suppressed code...)
  else if ( 0 == zeroSuppData )
    (...none zero suppressed code...)
  else
    (...-1 would be seen if an error occur,
        which should have been handled after function call,
        need to check anyway otherwise it might be dealt with
        by an above case...)

  (...)



dyn_int fwUkl1_parseReadRegisterSections const dyn_char &  dcData,
unsigned  numSections,
unsigned  sectionGap,
unsigned  startBit,
unsigned  length,
bool  fpga,
dyn_string &  exceptionInfo
 

The purpose of this function is to take the data read from the UKL1 registers and to allow multiple groups of continuous bits to be return in the form of a integer array. The function poses the ability to deal with registers of any size e.g. the 32-bit registers from the GBE or FPGAs, or the 8-bit registers from the I2C. It is also capable of dealing with the format of the FPGA registers as read from the UKL1s and a boolean switch it used to indicate that these must be handled. Typically this will be used with monitored registers.

Parameters:
dcData Data read from the register as a byte array.
numSections This is the number of times the defined section of data is to be read. It should be be defined by the the library constants that define the number of components on the board. For example FWUKL1_FRONT_FPGAS to retrieve the same setting for all the FE FPGAs when stored in the same register. This is set to 1 when only a single section need be removed. Each section is returned as an element in returned array. The first element contains the bits at startBit then subsequent elements contain the sections starting at the next section of bits.
sectionGap The number of bits between the last bit in a section and the first bit in the next section.
startBit Number of the first bit to be read from the register, where bit 0 is the least significant bit.
length Number of bits to be read, set to 1 if only startBit is to be read. Maximum 32.
fpga Boolean value to indicate whether we are parsing FPGA registers or not. This must be set correctly otherwise the data will not be properly interpreted.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
int Unsigned integer representation of the bits if the function is successful or -1 if it fails.
This function primarily designed to be use with registers that contain multiple settings in a single register that are a constant number of bits apart and are the same number of bits in size. This is most effective when dealing with the FE FPGA or channel registers to implement a broadcast mode.
The reason for the FPGA flag is that the UKL1 FPGA registers are read as if they were 32-bit registers and not the 16-bit registers that they are physically (this is because sequential addresses are 32-bits apart and not 16!). This function will remove the extra two junk words that are read and parse only the remaining data in this case. Do not remove these extra words manually before hand. This function can return sections that are a maximum of 32-bits in length. The only registers that are bigger than this are the MAC addresses and these have their own dedicated convertion functions. The input size of the register is unlimited.

Example:

  (...)
  //Fictional UKL1 board name, as found in the DIM server.
  const string ukl1Name = "pcukl101";
  //Register name needs to be the full DP name, hence requires the HW DP name prefix defined by this library.
  dyn_string registerNames;
  registerNames[1] = FWUKL1_HW_DP_NAME_PREFIX + ukl1Name + ".FeFpga0.disable"
  //Stores the read data.
  dyn_char readData;
  //Holds errors.
  dyn_int callStatusList;
  //Read and save the status.
  const bool readStatus = fwCcpc_read(registerNames, ddcData, callStatusList);
  //Check for errors...
  if (!readStatus)
    (...)

  //Data read from the disable register on the FE FPGA contains the disable settings for all the FE FPGA disable setting.
  //we split this data up into 4 settings, thus requiring only one read to get all the data.
  //Number of sections wanted is the number of FE FPGAs.
  const unsigned numSections = FWUKL1_FRONT_FPGAS;
  //The settings are in adjacent bits.
  const unsigned sectionGap = 0;
  //The data is a single bit, the first one starting at bit zero.
  const unsigned startBit = 0;
  const unsigned length   = 1;
  //The it is a setting on an FPGA register.
  const bool fpga = TRUE;
  //Check for errors.
  dyn_string exceptionInfo;
  //Convert the data.
  const dyn_int feFpgaDisableData = fwUkl1_parseReadRegisterSections(ddcData[1], numSections, sectionGap, startBit, length, fpga, exceptionInfo);
  //Check for errors.
  if ( 0 < dynlen(exceptionInfo) )
    (...)

  //Let us deal with all four settings.
  for (int feFgpa = 1; feFpga <= FWUKL1_FRONT_FPGAS; ++feFpga) {
    if ( 1 == feFpgaDisableData[feFpga] )
      (...disabled code...)
    else if ( 0 == feFpgaDisableData[feFpga] )
      (...enabled code...)
    else
      (...-1 would be seen if an error occur,
          which should have been handled after function call,
          need to check anyway otherwise it might be dealt with
          by an above case...)

  (...)



void fwUkl1_parseTtcrxReadRegisters string  ukl1Name,
const dyn_string &  registerNames,
dyn_dyn_char  ddcData,
dyn_string &  data,
const dyn_int &  callStatusList,
dyn_string &  exceptionInfo
 

This takes the data read from the TTCrx registers in the format as read from fwCcpc_read() or fwHw_getRecipe() and returns the values as a decriptive string.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
registerNames dyn_string that contains the name of the HwTypeCCPCUKL1 datapoint elements to be read from, which corresponds to the appropriate hardware register. The accepted names are:
  • IACId Requires a two byte word.
  • I2CId Default data format, see below.
  • FineDelay1 Default data format, see below.
  • FineDelay2 Default data format, see below.
  • CoarseDelay Default data format, see below.
  • Control Default data format, see below.
  • Status Default data format, see below.
  • Config1 Default data format, see below.
  • Config2 Default data format, see below.
  • Config3 Default data format, see below.
  • SingleErrCnt Default data format, see below.
  • DoubleErrCnt Default data format, see below.
  • SEUErrCnt Requires a two byte word, read only.
  • BunchCnt Requires a two byte word, read only.
  • EventCnt Requires a three byte word, read only.
ddcData This contains the raw data that has been read back from the PVSS datapoint.
data dyn_string returned by reference that contains a string representing the value in the register. It will either be a hex representation, zero padded to the nearest byte boundary or a text description of the settings. In the event that the read failed it will contain the text `Fail'.
callStatusList This is the status list returned by the fwCcpc_read function and if the data to be parsed was generated by the use of this function then a callStatusList should be passed in order that errors can be checked for. It is possible, for example via monitoring or reading from a recipe, that the fwCcpc_read function is not used and in this case an empty array should be passed and it will be ignored. Any errors found in this array will be reported via the exceptionInfo.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.

void fwUkl1_parseTtcrxWriteRegisters string  ukl1Name,
dyn_string &  registerNames,
dyn_string  sData,
dyn_dyn_char &  ddcData,
dyn_dyn_char &  masks,
dyn_string &  exceptionInfo
 

This function takes the data for the various TTCrx registers described by a string and converts it to data that can used with fwCcpc_write() or fwHw_saveRecipe(). It allows data to be given in a more human readable format and converts it to the byte array required for writting to the CCPC. It also returns the appropriate mask that must be used when writing the data. If being used with fwHw_saveRecipe() then the mask will have to be appended to the data array.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
registerNames List of GBE register names that are to be written to. Returned with the appropriate name prefix by reference. The allowed values are:
  • IACId Requires a two byte word.
  • I2CId Default data format, see below.
  • FineDelay1 Default data format, see below.
  • FineDelay2 Default data format, see below.
  • CoarseDelay Default data format, see below.
  • Control Default data format, see below.
  • Status Default data format, see below.
  • Config1 Default data format, see below.
  • Config2 Default data format, see below.
  • Config3 Default data format, see below.
  • SingleErrCnt Default data format, see below.
  • DoubleErrCnt Default data format, see below.
  • SEUErrCnt Requires a two byte word, read only.
  • BunchCnt Requires a two byte word, read only.
  • EventCnt Requires a three byte word, read only.
sData Data to be written to the registers in the form of a hex string. The default value is an 2-character hex string, other values are accepted for specific registers as described above.
ddcData sData converted into a dyn_dyn_char for use with the fwCcpc_write function. Returned by reference.
masks Masks that are associated with the write data.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.
Improperly formatted data will be removed from the list of write registers and will be indicated by an increased size of the exceptionInfo array.

void fwUkl1_ttcrxRead string  ukl1Name,
bool  readRecipe,
const string &  recipeName,
dyn_string  registerNames,
dyn_string &  data,
dyn_string &  exceptionInfo
 

This reads from a given set of TTCrx registers. The reads can either be from the hardware or they can be done from a configurationDB recipe.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
readRecipe If TRUE then the function will read the settings from the given recipe name and return the settings contained within. FALSE and the returned values will come directly from the hardware registers.
recipeName Name of the recipe to save the configuration information to if writeDb=TRUE, not used if writeDb=FALSE. The recipe must be of the form "RUN_TYPE/FsmAction", where RUN_TYPE is type of run that the recipe is to be loaded e.g PHYSICS, CALIBRATION, can take any value, but should be descriptive of the type of run the recipe settings represent; FsmAction is the action in the FSM when these settings should be loaded e.g. Configure if the recipe is to be used to moved to the READY state, typically only the first letter is upper case.
registerNames dyn_string that contains the name of the HwTypeCCPCUKL1 datapoint element to be read from, which corresponds to the appropriate hardware register.
data dyn_string returned by reference that contains a string representing the value in the register. It will be zero padded to the nearest 32-bit word.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.

void fwUkl1_ttcrxWrite string  ukl1Name,
bool  writeRecipe,
const dyn_string &  recipeNameAndType,
dyn_string  registerNames,
dyn_string  data,
bool  verifyWrite,
dyn_string &  exceptionInfo
 

This writes to a given set of registers on TTCrx. It can be used to write to either the registers on the UKL1 board or to a configurationDB recipe.

Parameters:
ukl1Name Name of the UKL1 board as it appears in the DIM server.
writeRecipe If TRUE then the function will write the given register settings to the configurationDB recipe given by recipe name. FALSE it will write the register settings to the UKL1 board.
recipeNameAndType Two element array containing:
  • Element 1 - The name of the recipe to save the data to. It must be of the form "RUN_TYPE/FsmAction", where RUN_TYPE is descriptive of the type of run the settings are saved for e.g. PHYSICS, CALIBRATION; FsmAction is the action of FSM state transition where the recipe should be loaded e.g. Configure, the first letter only should be capitalised.
  • Element 2 - The second element contains the recipe type that it is to be saved to, this can be anything provided it already exists. This array is only required if writeRecipe=TRUE, otherwise it can be empty.
registerNames dyn_string that contains the name of the HwTypeCCPCUKL1 datapoint element to be written to, which corresponds to the appropriate hardware register. The accepted values are described in fwUkl1_parseGbeWriteRegisters();
data By default an 8-bit value that is to be written to the register represented as a hex string, it need not be zero padded. Certain settings accept or require an alternative format as described for each register above.
verifyWrite If this is set to TRUE then the register will be read back from to ensure that the data written corresponds to that read. Default: FALSE.
exceptionInfo Error information. If dynlen is zero no errors occurred. The standard error codes (defined in library documentation) are used.
Returns:
void.


Generated on Tue Jul 3 17:05:51 2007 by  doxygen 1.3.9.1