pitFed (Pixel Trigger Driver) software development page

This page last update -- GianlucaAglieriRinella - 23 Oct 2008

• PitDatabase

General information material

• pitFed software documentation
• File listing the commands that the pitFed understands
• PIT memory map, global pit_memory.pdf: Design notes describing the global addressing space of the PIT system
• registers_map.xls: Excel table describing the memory addresses of the OPTIN registers in a given OPTIN section of the global memory space
• brain_registers_map.xls: Excel table describing the memory addresses of the PROCESSING FPGA registers, offset 0x1000000 in the global memory space

VHDL files of OPTIN and Processing FPGAs

This section last update -- GianlucaAglieriRinella - 29 May 2008

• optin_command_decoder.vhd: VHDL code of the OPTIN board command decoder, contains the list of all the commands recognized by the OPTIN. Commands need to be written to the 0x2 address of the given OPTIN address space
• proc_command_decoder.vhd: VHDL code of the Processing FPGA command decoder, contains the list of all the commands recognized by the PROCESSING FPGA. Commands need to be written to the 0x2 address of the processing fpga address space
• fastor_logic.vhd: VHDL file of the processing logic block in the PIT processing FPGA. Implements various trigger algorithms. Defines connection of the algorithm outputs to physical outputs. Contains the values for the dinamically configurable output

List of todo for the pitFed driver software

• (TO DO) pit_driver programmer method to program the FPGA
• (TO DO) change delay to 4 bits, DB and pit_driver
• (TO DO) Clean up documentation
• (TO DO) implement the file exchange server interface
• (TO DO) Fix automatic detection of TTCrx chip, not working all the times
• (TO DO) Implement further functionalities (reset) for the TTCRx chip
• (TO DO) add a field for the TTCrx chip clock delay register setting in the database configuration (or not??)
• (Work in progress) Define with ECS an FSM command that will have be issued to the pixel trigger every time a run starts that uses the pixel trigger as one of the
• (TO TEST) the prog done pin problem was solved, now it needs to be tested
• (DONE) implement the I2C functionalities in the dedicated class
• (DONE) The selection of the cosmic algorithm has been modified in latest processing firmware. Software functions to select the cosmic algorithm need to be updated as well. Now the selector is the Parameter 0 in group 9 (address 7A in the processing register space 0x100007A), it is given by the 4 least significant bits of that register. * (DONE) had the user name and user comment to the link confguration and firmware configuration tables
• (DONE) create commands to check which configuration versions the driver is using at the moment (link, firmware and parameters), useful for PVSS
• (DONE) add special parsing to the create new database version commands, user name and comment have to be separated by '"'
• (TO DO) Saving a new firmware configuration version to the database
  • (DONE) Class that interfaces with the firmware version tables (both saving to the database and applying to the hardware)
  • (DONE) method to parse a firmware definitions file (even though the format of this file might change in the future)
  • (TO DO) Embed the code of the svf2ace Xilinx utility in the pitFed software in order to avoid the intermediate step of generating the ace file.
  • (TO DO) Define in detail the procedure to commit a new firmware version to the database starting from scratch. Needs text files?
  • (TO DO) Logging functionality: file appender might be modified to use a roll-over file to avoid risk of filling disk space
• (DONE) Implement function to generate a file to be exported to offline containing the pixel chips used as triggering input and the pixel trigger configuration
• (DONE) Implement functions to read/check the prog pin of the processing and optin fpgas. Implement function to read firmware versions. Implement more advanced remote programming function that does logging/check of programming pin status/reading of firmware version.
  • Created a function for the higher level programming Even though the prog done pin is always low for the processing FPGA
• (DONE) Database tables to be updated to separate the three identifiers to fully define a configuration version
• (DONE) Define in detail the procedure to commit a new firmware version to the database starting from existing firmware, but modifying the parameters.

• (DONE) Define and implement appropriate hardware data polling strategy: time interval, data, what in case of hardware access error
• (DONE) (Gianluca) Functions to use the remote reprogramming functionality. Tested with hardware.
• (WORKING) Configuration management
  • (DONE) Installation of the C++ Oracle access library on (DONE) alipitwn002 (pitFed), (DONE) pcald19 (DSF, workarounds. Oracle was compiled with modules not fully compatible with oracle, warnings issued but seems to work), (DONE) pcald22 (lab, working, no warnings. Same version than pcald19, but older OS version, fully compatible with oracle).
  • (DONE) Design the tables and fields for the PIT configuration database
    • Three iterative meetings between Cesar and Gianluca foreseen. First meeting is to define a design proposal. Should be during week 44 (also ALICE week) after the general SPD meeting
  • (DONE) New pitDatabaseInterface class in the pitFed to interface to the Oracle database. This class knows the details of the database (tables, fields). It provides methods that execute the queries on the DB (using the Oracle interface). The methods return to calling functions the values retrieved from the database in data structures independent from the database details.
    • In a first phase read only functionality is required. Database writing functionalities might be implemented in a dedicated separate sowftware tool
    • Coding of this class and of the following modifications might take one week
  • (DONE) Modify the existing pitConfig class to contain one instance of the pitDatabaseInterface class. Add methods to populate the pitConfig data structure by calling the methods of the pitDatabaseInterface object. The pitConfig class contains the storage for the data of the active configuration. It already provides in its interface functions for the other driver classes to retrieve configuration values to set in the hardware
  • DONE Configurator class member function to retrieve from a file the correspondence between pit channels and MCMs and functions to convert from (Sector,Side,Half Stave, Chip) coordinates to (Optin Board, Link, Chip) coordinates and vice versa.
  • (DONE) Configurator class member function to determine if a given fochannel and link is required in a required configuration or not. Info can be stored in a local file (for initial implementation) or in a remote database
  • (DONE) pit_driver_procFpga member function to mask an optin board in the HW, at the level of inputs to the Processing FPGA (new functionality bit <0> of Processing FPGA setting registers) (cesar:the software is writing to the correct addresses a little more testing is needed)
  • (DONE) Member function to reload all configuration from file or database. Called by the constructors as well.
  • (DONE) Automatic masking (in HARDWARE) of all chips, half staves, optin board that are marked as not required in the configuration file
    • (DONE) Constructors should: check if a chip is required and mask it in HW (if the board is plugged) (needs more checking in the memory positions)
    • (DONE) If an OPTIN board is not plugged (rather: ALL of its links and chips are masked) then this should be masked in the processing FPGA device
  • (DONE) Add a linkDelay column in the linkConfigurationFile This value is also to be written to HW in the reconfiguration procedure (member functions already there) (cesar: see above)

• DONE New setters and getters in the processing fpga class for the programmable parameters of the algorithms. Storage is in the processing memory area, starting from address 0x1000071 (see attached file brain_registers_map.xls). Three parameters (0, 1, 2) are foreseen. Parameter 0 is up to 12 bits, parameters 1 and 2 up to 10 bits.
  • setAlgorithmParameter(unsigned int algorithmNumber, unsigned int parameterNumber, unsigned int parameterValue) in which: algorithmNumber can be from 0 to 9 (for the moment) and determines the memory address; parameterNumber can be from 0 to 2 and determines bit range; parameterValue is the new value to store in the defined location. WARNING: when setting values one has to read first the present value in the HW, update the bit field of the new parameter and then store the new register value.
  • getAlgorithmParameter(unsigned int algorithmNumber, unsigned int parameterNumber) in which: algorithmNumber can be from 0 to 9 (for the moment) and determines the memory address; parameterNumber can be from 0 to 2 and determines bit range; reads the previous value.
  • DONE DIM commands to call the previous two methods

• DONE New setters and getters in the processing fpga class for the selection of the cosmic trigger algorithm (physically connected to last output 9). Storage of the selector parameter is in the processing memory area, at address 0x1000018 (see attached file brain_registers_map.xls). The selector field is 4 bits.
  • setCosmicAlgorithm(unsigned int comicAlgorithmNumber) in which: comicAlgorithmNumber can be from 0 to 5 (for the moment) and determines the coincidence logic algorithm presented to output 9. Refer to attached file fastor_logic.vhd for details and algorithm labels, see block BLOCK_COSMIC_ALGORITHM_SELECTOR from line 352.
  • getCosmicAlgorithm() getter of the cosmic algorithm selector value.
  • DONE DIM commands to call the previous two methods
  • DONE new DIM Service publishing the label of the cosmic trigger logic selected (useful for indication on the PVSS panel), refreshed on update of the cosmic selector. Constructor should read the value and update this service also on driver startup.

• Definition and implementation of classes for status storage and control of:
  • DONE Processing FPGA
    • DONE Functions to set output modality
    • DONE Readers of Fast-OR counters
  • DONE Control FPGA
  • DONE Fast OR channel

• DONE Refine the logging mechanism

• DONE Definition of the pit DIM commands ("CONTROL_COMMAND;side;sector;half_stave;chip", "READWORD;addr", "WRITEWORD;addr;data")
  • DONE Implementation of the DIM commands manager; it receives DIM commands, parses the list of parameters and calls the proper daa

• DONE Basic DIM commands to write/read to/from pit memory location a single value

• WORKING Definition of the list of DIM services that the driver has to provide
  • DONE Status services for detector components
  • DONE Status services of the communication driver (communication error flag)
  • DONE Implementation of the DIM services
  • DONE Implement ID mechanism for the command execution and feedback
    • (TO DO) Check if this is compliant to DCS recommendations and if a dedicated feedback service is to be provided
  • DONE Ten services to publish the status of the ten pit main outputs

• WORKING Configuration management
  • DONE Configurator class member function to retrieve from a file the correspondence between pit channels and MCMs and functions to convert from (Sector,Side,Half Stave, Chip) coordinates to (Optin Board, Link, Chip) coordinates and vice versa.
  • (DONE) Configurator class member function to determine if a given fochannel and link is required in a required configuration or not. Info can be stored in a local file (for initial implementation) or in a remote database
  • (DONE) pit_driver_procFpga member function to mask an optin board in the HW, at the level of inputs to the Processing FPGA (new functionality bit <0> of Processing FPGA setting registers) (cesar:the software is writing to the correct addresses a little more testing is needed)
  • (DONE) Member function to reload all configuration from file or database. Called by the constructors as well.
  • (DONE) Automatic masking (in HARDWARE) of all chips, half staves, optin board that are marked as not required in the configuration file
    • (DONE) Constructors should: check if a chip is required and mask it in HW (if the board is plugged) (needs more checking in the memory positions)
    • (DONE) If an OPTIN board is not plugged (rather: ALL of its links and chips are masked) then this should be masked in the processing FPGA device
  • (DONE) Add a linkDelay column in the linkConfigurationFile This value is also to be written to HW in the reconfiguration procedure (member functions already there) (cesar: see above)

• (DONE) TIN-DET server to allow outputs control seems to work well
  • From the analysis of the TIN-DET example provided by the trigger group one can understand that they expect:
    • A DIM command with name "SPD/SET_OPTIONCODE" and accepting "L:2" (two long int DIM types) arguments. If arg is the array of the two arguments, then arg[1] is the CTP input number (range: 1,2,3 ... MAXCTPINPUTS), while arg[0] is the mode code ( 0 for normal N, 1 for toggling T, 2 for signature S, 3 for random R)
    • A DIM service with name "SPD/STATUS_OPTIONCODE" publishing a char array of MAXCTPINPUTS+1 elements (the +1 is for the \0 end of string character). Each char of the array can be one of N, T, S, R for the mode of the corresponding (by order) output.

• DONE Commands
  • (DONE) Commands to start and stop the OPTIN boards counters, hardware function exists.
  • (DONE) Command to start and stop ALL PIT counters "simultaneously" (this calls commands implemented at the previous point)

• (DONE)
  • (DONE) Functionality and data members to start stop counters added to the pit and driver (see pit_driver_opticalLink.cpp)
  • (DONE) Add pitFed command to use those
  • (DONE) Same thing for the commands to start stop all counters, needs a method in the pit_driver_optinBoard class and related command sintax

• (DONE)
  • (DONE) Change the DELAY setting and reading for a link, because of hardware change. Now it is 4 bits, <31:28>, value can be from 0 to 15.
    • Looked if the settings register for this link was being properly written. Had a minor bug in the start position, but it was easy to spot
  • (DONE) Command to set the masks of the 10 chips in a half stave in a single command access to speed up masking from PVSS (the class already had the method so should work, maybe some minor mistake in the command deconding)
    • Again, looked to the settings register for this link and saw that everything was ok
  • (DONE)Command to reload the link configuration from the file and load it in the pit (chip masks and link delays)
    • command implemented if you send an empty string as filename reloads the current default configuration without loading the file

• • (DONE) Dinamically configurable level of logging (by command)
    • cesar: had to look a little into iterators and stl, but its working now, tested with the file logging threshold (I will have to check the PVSS to test the dim threshold, claudio is using it) but should work, the code is the same
  • (DONE) check for the syntax of the existing read_time_stamp command. The parameters list did not seem to me (Gianluca) correct, there should be three timestamps per each link, check on the OPTIN registers file above
  • (DONE) introduce a read back also of the Processing FPGA version number after the control in function PITCheckCommStatus(). This should protect against the strane repeatable bug found by Claudio: after a failing read access a write access apparently sends the system into stall! If a read access is executed afterwards, then everything keeps working normally.
  • (DONE) check for the correspendence between our numbering of outputs and CTP numbering of inputs, i.e. check that when they change the mode for output n this is actually applied to our output n-1
  • (TO DO) make sure that the manual setting of the FastOR masks also has the following behavior: if the user is (by commands) masking all chips in a given link then that link status changes to not required, i.e.its data member required is also set to false
  • (DONE) new pit_driver.autoConfigureDelays() method to determine optimal delay settings after a single L1 trigger has been strobed. ALso the command to launch the method is needed. The method should:
    1. loop through all links that are locked and required
    2. read for each of them the time stamp register 1, determine the minimum and the maximum value of all the timestamp values
    3. check that the difference between maximum and minimum time stamp is a small integer in [0;4] interval. If this is NOT the case then stop algorithm logging an error messages reminding the user to
       1. make sure all routers can receive ttc triggers, i.e. their exclude ttc flag is OFF
       2. make sure to issue a resetFEE command form the LTU control
       3. make sure to open a calibration run and send at least one trigger sequence and that this is received by all Half Staves enabled for triggering
    4. (max-min difference smaller than or equal to 4) loop again through all links that are locked and required and set their delay to a value equal to the difference between the maximum of the timestamps determined before and their actual timestamp, so to bring all phases aligned to the link receiving the timestamp as latest
  • (DONE) new pit_driver.autoCheckPhases() method to verify that all links that are locked and required have the same phase. ALso the command to launch the method is needed. The method should:
    1. loop through all links that are locked and required, count them and read their phase and fill a histogram (this has bins for phases entries 0,1,2,3) of the phases distribution
    2. after the loop log the 4 values of the histogram, check that the histogram has three bins with value 0 and only one with a number of entries equal to the number of links that are locked and required, i.e. verify that all links have the same phase
    3. if this is not the case, then log a warning message to the user recommedning to check the proper settings of the link delays

• • (NOT NECESSARY) pitFed command to execute a timestrobe command on the OPTIN boards. This enables the strobing of the arrival time of the HS Fast-OR and of the L1_FBACK. Check above for the file describing the command recognized by the OPTIN command decoder. The pitFed command for this strobe_timestamp should have parameters sector, side and link (these define the OPTIN board to which the command is to be sent)

• Bugs to fix
  • (DONE) If an exception is thrown by the otpin object constructor there is nothing to catch it and the driver terminates
  • (DONE) Uniformity of behavior for the loggers, we suspect that some categories have NOT been added the DIM Appender.

Minutes of meetings with working info and related material

24/07/2007, Fabrice, Gianluca, minutes

• minutes_meeting_PIT_2007-09-24.pdf: Minutes of the meeting between Gianluca and Fabrice of 24/09/2007

22/10/2007, Fabrice, Gianluca, minutes (txt)

• minutes_meeting_PIT_2007-11-21.txt: Minutes of the meeting between Gianluca and Fabrice of 21/11/2007