Front-End Control Supervisor Documentation

News:

September, 2004 - A new FEC web page exists on the internal CERN network (you need to be log on CERN network to access it) at the web address http://x5oracle.cern.ch:8080/JSPWiki/Wiki.jsp. Many over information needed are given on this new web page. With the time all information here will be removed to be moved to the new web page.

March, 2004 - Merge the two FEC driver 16/32 bits in the same layer that need no more compilation for the high level layer (glue to FecSupervisor).

December, 2004 - The same driver is able to compile both version of the FEC, electrical, optical

Tuesday, November 18, 2003 - cms-support-fec-software

July, 2003 - stable0703 is available



List of items:

Documentations:



Introduction:

All the API and tools are not dedicated to the Tracker sub-detector, but it is tested in the Tracker some many tools used the Tracker electronic devices for test. We/You can modify the program (ProgramTest / FecProfiler / FecSupervisor) in order to fit to your requierements. The ProgramTest tools can be modify by yourself (adding some specicic test program) and for the FecProfiler / FecSupervisor you must follow the following guideline.

We are available to help you. Any modification can be submitted to us and can be integrated in our software.

Authors:



System requierements:

The classes defined in this program are used to manage a part of the CMS Tracker control. This part covers all the accesses for the Front-End Controller (FEC) part. It must be used with the FEC device driver developed by the Alsace group.

This system is based on the XDAQ system in order to fit with all the specification of the CMS data acqusition system.

This work is done and tested for Linux Redhat distribution on PC. That was tested for the RedHat CERN distribution 6.X, 7.X. Note that this software works also on Debian, Suse, ... distribution.

The kernel supported are:

Compiler: gcc and g++:

TriDAS

Database:



How to get the software:

Get and compile the software

The script configure.sh is the best way to retreive and compile all the FEC software

Several options can be used (type configure.sh help to display it).

Usage ./configure.sh [-prefix ] [-domaindir ] [action]

To install compile the last stable version of the FEC software, type: To update and compile the software, type: To build the documentation, type:

By this way, you will able to retreive the complete architecture for the FEC and compile it:

To compile this software, you have to edit the script if you want to install in over directory than ${HOME}/FecSoftware and change:

CVS on the CERN server:

This version is under development and you can have problems to compile and excute software.

Please refer to the CERN CVS page for any problem:



How to build the software:

You can use the FEC C++ API in standalone program or in the XDAQ framework.

Options to be configured:

Once you have installed the software, you may want to compile the complete software. If you have done a complete installation with option install, the software is compiled. You can also modificate several options described now.

First, be sure that you have downloaded, compile the XDAQ application and set your PROJECTDIR (TriDAS 1.2) / XDAQ_ROOT (TriDAS 1.3) environment variable (if you want to use XDAQ application).

Edit the FecSoftware/FecSupervisor/FecHeader.linux file and set your options (depend of your system). If the file is not there, copy it from FecSoftware/FecSupervisor/config/FecHeader.linux. Note that all the modifications can be done directly by using the automatic procedure

Build the different programs:

 Note that you don't need to do the compilation if you have used the configure.sh script. But the makefiles can be used if you need to recompile it.
You have first to compile the device driver and install it (as admisnitrator root):

Note that you can have several warnings on a Linux kernel 2.2.X:


This warning is due to the installation of the system (conflict between kernel include file and STL::map).
Once you have compiled the device driver, you can compile and start the differents programms available:

You can find on the FecSupervisor/xml directory several files:


See the tools available for the differents programs and options.

Build the documentation:

To build the documentation, you go in the FecSupervisor/doc directory and type doxygen:

If you don't have doxygen, this documentation is available to this web page.
Note that if the FEC supervisor links (to the class) don't work in this page, build the documentation.

Tools available:

Note that all this tools are compiled and installed when you install the software througth the configure.sh script.

Several programs are available:

Console debugger: dd_console_debugger
  • cd FecSoftware/Thirdparty/dd_console_debugger
  • make
  • ./debugger.bin You have the following menus with the different options:
    • 0 : Quit
    • 1 : Write to control 0
    • 2 : Read control 0
    • 3 : Write control 1
    • 4 : Read status 0
    • 5 : Read status 1
    • 6 : Write to fifotransmit
    • 7 : Read from fifotransmit
    • 8 : Write to fiforeturn
    • 9 : Read from fiforeturn
    • 10 : Write to fiforeceive
    • 11 : Read from fiforeceive
    • 12 : Dump PLX config
    • 13 : Dump PCI config
    • 14 : Reset users counter to 1
    • 15 : Enable (or Re-enable) PLX interrupts
    • 16 : Disable PLX interrupts
    • 17 : init TTCRX
    • 18 : Resets PLX
    • 19 : Resets FEC
    • 20 : OLD CCU ONLY : Full Scan Ring - WRITE to devices
    • 21 : OLD CCU ONLY : Full Scan Ring - READ from devices
    • 22 : OLD CCU ONLY : Context switch delay measurement
    • 23 : NEW CCU (i.e. CCU 25) ONLY : Full Scan Ring - WRITE to devices
    • 24 : NEW CCU (i.e. CCU 25) ONLY : Full Scan Ring - READ from devices
    • 25 : NEW CCU (i.e. CCU 25) ONLY : Context switch delay measurement
    • 26 : Dump PLX raw base addresses
    • 27 : Dump PLX remapped base addresses
    • 28 : Enter a frame and send it to the ring ; RAW write method used
    • 29 : Enter a frame and send it to the ring ; glue_fec_write_frame write method used
    • 30 : Read back a forced-ack or data frame (transaction number requested)
    • 31 : OLD CCU ONLY : Quick scan ; detect only CCU's on ring
    • 32 : NEW CCU ONLY : Quick scan ; detect only CCU's on ring
    • 33 : Write frame and read back direct ack and forced ack / data
    • 34 : Transcript error code into clear message
    • 35 : Loop a write/readback sequence of command issued from a file.
    • 36 : Ring Error Management sub-menu.
    • 37 : Read current PLX reset counter.
    • 38 : Read current FEC reset counter.
    • 39 : Read Driver General Status Word.
    The most usefull options are:
    • 4: Read status 0 - in order to retreive the FEC status register 0.
    • 18: PLX Reset - reset all the FEC/ring/CCUs. The PLX is the PCI bridge use for the FEC board
    • 19: FEC Soft Reset - software reset of the FEC
    • 21 or 24: CCU Complete Scan Ring (CCUs + devices) - scan the ring to the CCU and for each I2C channel/address available (0x0 - 0xFF) try to access ato any hardware device register (normal write single byte and force acknowledge). You have no garentee that the hardware (example the extended/RAL mode device) is fine.
    • 31 or 32: CCU Quick scan ; detect only CCU's on ring - just detect the CCU on the ring.

    High level debugger: ProgramTest

     It allows all the access to specific hardware. The program test used the C++ API. You must compile it (if it's not done) start it.
      NAME
        ./ProgramTest - tests for all FEC / CCU / I2C / PIA / MEMORY functionnalities

      MOST USEFULL OPTIONS AND COMMANDS ARE:
      • ./ProgramTest: retreive the FEC status register 0
      • ./ProgramTest --help: for help
      • ./ProgramTest -scanring: to scan ring for CCUs
      • ./ProgramTest -scanringdevice: to scan ring for CCUs and Tracker device (APV, MUX, PLL, Laserdriver, DOH, DCU). Only one access to the base register is done in the right I2C mode (RAL, normal mode, depend of the device type).
      • ./ProgramTest -ccu 0x7F -channel 0x1b -tracker apv pll mux dcu laserdriver doh: if a paremeter is not set (FEC/RING/CCU/channel), the default is used (in the previous example FEC slot and ring slot are 0). You can one or several device type (apv pll mux dcu laserdriver, DOH).
      • ./ProgramTest -pia: test the pia channels for different operations (initialisation/read/write operations) (only for CCU 25)
      • ./ProgramTest -memory: perform some test on the memory channels (only for CCU 25).

      SYNOPSIS
        ./ProgramTest [ OPTIONS ] COMMAND [ ARGUMENTS ]

        List of commands:
        ./ProgramTest -help
        ./ProgramTest
        ./ProgramTest -scanring
        ./ProgramTest -status
        ./ProgramTest [-fec x] -scanringdevice
        ./ProgramTest [-fec x] -scanringedevice
        ./ProgramTest [-errorCounter [file]] [-loop [n[-t]]] [-fec x] [-ring x] [-ccu x] [-channel x] -pia
        ./ProgramTest [-errorCounter [file]] [-loop [n[-t]] [-fec x] [-ring x] [-ccu x] [-channel x] -piaReset [value-delayActiveReset-intervalDelayReset]
        ./ProgramTest [-fec x] [-ring x] [-ccu x] [-channel x] -memory
        ./ProgramTest [-fec x] [-ring x] [-ccu x] [-channel x] -memoryPerf [number]
        ./ProgramTest [-fack] [-loop [n[-t]] [-Tmode t] [-fec x] [-ring x] [-ccu x] [-channel x[-xx]] [-deviceAddress x] -i2c
        ./ProgramTest [-errorCounter [file]] [-loop [n]] [-noFack] [-fec x] [-ring x] [-ccu x] [-channel x[-x]] -device
        ./ProgramTest [-errorCounter [file]] [-loop [n]] [-noFack] [-fec x] [-ring x] [-ccu x] [-channel x[-x]] -tracker
        ./ProgramTest [-fec x] [-ring x] -fileCommand file
        ./ProgramTest [-fec x] [-ring x] -key index

      DESCRIPTION
        All the values specified by x/xx must be given in hexadecimal (with or not "0x" before). For the others values, there must be specied as a radix 10 integer value. The character case of the options/commands are not important. Policy: [] means optionnal parameters.

      OPTIONS
        List of the options:
        [-fec x] Specify the FEC slot in hexadecimal (default = 0x0)
        [-ring x] Specify the ring slot in hexadecimal (default = 0x0)
        [-ccu x] Specify the CCU address in hexadecimal (default = 0x7F)
        [-channel x] Specify the channel in hexadecimal (default = 0x1B)
        [-channel x-xx] Specify a range of channels in hexadecimal
        [-deviceAddress x] Specify the I2C address in hexadecimal (default = 0x20)
        [-Tmode t] Specify the device type: APV, MUX, PLL, DCU, LASERDRIVER, DOH
        [-fack] Force acknowledge used (default)
        [-noFack] Do not use the force acknowledge. Note that some requests due to the FEC bandwith can have problems.
        [-loop] The program will made an infinite loop (see below)
        [-loop n] Make n loop. If the value is negative or no value are specified, the program will made an infinite loop.
        [-loop n-t] Same than the previous command but wait between each command t microseconds.
        [-errorCounter [file]]
          Display error counters and FEC/CCU status with the error.
          If a file is specified, dump all the messages to the file.
          If no file are specified the output is on stderr

      COMMANDS
        With no command
          Open the device driver slot 0 and display the control register 0 and the device driver status
          No option nor command are needed
        -help
          Display this help.
          No option is needed
        -reset
          PLX and FEC reset.
          No option is needed
        -scanring
          Find all the device driver loaded for FECs
          Scan the ring for each FEC to find all the CCUs.
          No option is needed
        -status
          Find all the device driver loaded for FECs
          Display all the FEC control and status registers
          Display all the device driver status
          Scan the ring for each FEC to find all the CCUs.
          Display all the CCC control and status registers
          No option is needed
        -scanringdevice
          For a FEC, find all the CCUs on the ring
          Find all the I2C Tracker devices connected
          Device available: APVs (all poss.), MUX, PLL, DCU, LASERDRIVER, DOH
          Note that the program try to read the base address (in the right mode) but not all the device registers are accessed.
          Options: [-fec x]
        -scanringedevice
          For a FEC, find all the CCUs on the ring
          Find all the I2C registers connected (address from 0x00 to 0xFF)
          Note that the program try to read from the address (in i2c normal mode) but not all the device registers are accessed.
          Options: [-fec x]
        -pia
          Test the PIA channel
          Use only with CCU 25, channels can be 0x30 to 0x33 for 8 bits long register.
          Options: [-errorCounter [file]] [-loop [n[-t]]] [-fec x] [-ring x] [-ccu x] [-channel x]
        -piaReset [value-delayActiveReset-intervalDelayReset]
          Test the PIA reset.
          Set the value given bit per bit, wait for delayActiveReset, Set 0xFF and wait for intervalDelayReset (default 0xFF-10-10000).
          The value must be given in hexadecimal and the delayActiveReset and intervalDelayReset must be given in microseconds (decimal) Use only with CCU 25, channels can be 0x30 to 0x33 for 8 bits long register.
          Options: [-errorCounter [file]] [-loop [n[-t]]] [-fec x] [-ring x] [-ccu x] [-channel x]
        -memory
          Test the memory channel
          Use only with CCU 25, channel can be only 0x40 (set by default)
          Options: [-fec x] [-ring x] [-ccu x] [-channel x]
        -memoryPerf [number of accesses]
          Test the performance for the memory channel in multiple read and multiple write, display the bandwith The number of accesses to be done can be specified (<= 65536)
          Use only with CCU 25, channel can be only 0x40 (set by default)
          Options: [-fec x] [-ring x] [-ccu x] [-channel x]
        -i2c
          Test the i2c write/read
          Test the access with the normal mode by write and read the values 0x0F to the address given (default address 0x0)
          Options: [-errorCounter [file]] [-noFack] [-loop [n[-t]]] [-Tmode t] [-fec x] [-ring x] [-ccu x] [-channel x] -[deviceAddress x]
        -device
          Write and read back the values in all registers of the given device type.
          Device type: apv, apv6 (all poss.), mux, pll, dcu, laserdriver, DOH
          Options: [-noFack] [-fec x] [-ring x] [-channel x[-xx]]
          Note that a range of channels can be specified
          Options: [-errorCounter [file]] [-noFack] [-loop [n[-t]]] [-fec x] [-ring x] [-ccu x] [-channel x] -[deviceAddress x]
        -tracker
          Write and read back the values in all registers of the given device type.
          Device type: apv, apv6 (all poss.), mux, pll, dcu, laserdriver, DOH
          Options: [-noFack] [-fec x] [-ring x] [-channel x[-xx]]
          Note that a range of channels can be specified
          Options: [-errorCounter [file]] [-noFack] [-loop [n[-t]]] [-fec x] [-ring x] [-ccu x] [-channel x] -[deviceAddress x]
        -fileCommand file
          Submit a file of frames (FEC/CCU frames) to a given FEC Possible tags in the file are:
          • noDisplay: Do not display any message
          • noWait: Do not wait after each frame
          • noClearErrors: by default, when an error occurs, a clear of the FEC control register are done (CR1 = 0x3 and CR0 = 0x1). If this command is set the clear is not performed
          • Frame: to send a frame over the ring. The direct ack is read back and display. Note that the transaction is fixed by the device driver so the value given is not important (for value 0xFE, see next command).
          • Frame: to send a frame over the ring and read back the direct ack and the answer of the frame
          • w FecRegister Value: write the given FEC register to the value given (FEC register are CR0, CR1, SR0, SR1).
          • - r FecRegister: read the given FEC register and display it (FEC register are CR0, CR1, SR0, SR1).
          Options: [-fec x] [-ring x]
        -key index
          Test a key value and display the FEC/RING/CCU/Channel/Address path
          The index must be given in hexadecimal.
          No option is needed

      DIAGNOSTICS
        When an error occurs, an C++ exceptions is thrown and displayed. Differents errors can arrived, depend of the command. Most of the access are i2c accesses and you can have error on FEC access, CCU access, channel access or device access. So take care about the address that you give. Please fill free to signal errors/bug to fec-support@ires.in2p3.fr. You can also submit modifications/adds to the same address.
     Remarks:

    XML tools for hardware accesses: FecProfiler

    This program is used in order to parse an XML file (see below) and depending of the parameter, download the values in the hardware. Once the download is done, the FecProfiler upload the values into a file (/tmp/output.xml).

    If the validating parser is set, XML file is parse and validate with a schema.

    Remarks:

    Graphic User Interface for debugger FEC, CCU, I2C channel, PIA/PIO channel, Memory channel, Tracker devices