Introduction

This document describes briefly the overall structure of the source code, project and IP core files and versioning strategy. Brief instructions on how to build the firmware are also provided

Repository and project structure

CMX comes in three types: Jet, CP and SumET. Each of these three types has a 'crate' and a 'system' variant giving a total of six firmware sets. A large fraction of the functionality such as backplane data capture, Topo data transmission, RTM data transmission and capture, spy memory and readout functions is common to all flavours. Modules implementing the common functions are stored in Common/trunk/sources. Common IP cores are stored in Common/trunk/ipcore_dir. Files that are specific to the type but are common between the 'crate' and 'system' variants are stored in directories of the form Type/Type_common/trunk where Type can be Jet, CP and SumET. There sources and ipcore_dir directories are located where source code and IP cores are stored. Finally the specific source, IP core and project files for each of the six firmware builds are in the directories of the form Type/Type_variant/trunk where Type is as above and variant is either system o crate. in these directories you will again find sources and ipcore_dir subdirectories. In each of the these directories a ISE project file named CMX_top_Base.xise can be found. In addition other project files (netlist files, partition files etc) as well as latest bit files are also located in these main project directories. Each of the firmware variant top level module is sources/CMX_top_Base.vhd

Versioning

CMX has three version registers (described in more detail in the main FW documentation) for each of the common modules, modules common between 'system' and 'crate' variants for a given type and modules specific to the given firmware variant. Common modules version is stored in Common/trunk/sources/CMXpackage.vhd under the constant version_common. Version for type common modules is stored in Type/Type_common/sources/CMX_flavor_package.vhd under version_flavor_common. Finally version for variant specific modules is stored in Type/Type_variant/trunk/sources/CMX_local_package.vhd under the constant version_flavor_local. It is advised that whenever files in a given directory are modified and firmware built the corresponding version constant is incremented.

Building instructions

Xilinx ISE 14.7 development environment is required to build the firmware. With the exception of SumET crate variant all variants require Smartxplorer to successful route the design while meeting the timing constraints (refer to Xilinx ug689). Therefore the Xilinx installation and the project directories should be available in a locations available from across a small cluster. Nodes that will be used for the build should be set up for access with passwordless ssh. It is also possible to set up Smartxplorer for batch system operation but this has not been attempted.

The first step is to check out the project using your favourite svn client from: svn+ssh://svn.cern.ch/reps/atl1calo/firmware/CMX/CMX_project/Base. Then navigate to the subdirectory corresponding to the variant of the firmware you wish to build and open the project file. The project options have been optimized and should not be modified for a successful build. Synthesis can be performed normally. One can expect about one hour for synthesis step to finish. Following synthesis Smartxplorer should be launched by selecting from the application menu: Tools->SmartXplorer->Launch SmartXplorer. This will open Smartxplorer dialog window. Here one should select to iterate over the cost tables and specify host list where the parallel jobs can be launched. It is recommended to launch approximately 15 cost table iterations for a successful Map+PAR run that finishes within reasonable time. One should expect about three hours for the first successful Map+PAR. Smartxplorer can be configured to terminate on-going iterations when first successful solution is found, to copy the achieved solution to main project directory. Note that each iteration consumes considerable amount of memory (~6GB) and temporary disk space (~2GB) - one must take these constraints into account when setting up the commonly available space and number of jobs per node. Smartxplorer makes no attempt to predict resource use, shall these resources be exhausted manual job termination and cleanup will be required.

Upon successful Smartxplorer run bit file can be generated in the standard fashion following ISE project flow. Finally CF card file system can be prepared using impact deploying the bit files corresponding to different CMX variants in different 'revision' slots as described in the board support documentation.

To create CF image:

run impact
On the 'Welcome to iMPACT' scree select: 'Prepare a System ACE File'
On 'Operating Mode' pop-up select 'novice'
On the next pop-up ('System ACE Compact Flash Size') leave the defaults
In the 'System ACE Name And Location' select the name of the CF file system (e.g. 'CMX') and create/select the location (e.g. /afs/cern.ch/user/x/youruser/public/CMX_ACE_date_rev/)
On the next pop-up 'System ACE Configuration Address And Design' check-off addresses 2 through 7. If you want to deploy special FW in slots 0 or one check these also. For the rest of this write up we assume you did not use special FW slots, but the process is analoguous
On the next pop-up 'System ACE File Generation Summary' click 'Finish'
Now a pop-up 'Add Device' will appear Stating 'Config Address: 2', click 'OK'
In the 'Add Device' pop-up navigate to the directory where the project is located, to the Base/CP/CP_crate/trunk directory and select CMX_top_Base.bit; click 'Open'
Pop-up will appear asking 'Would you like to add another device file to Config Address: 2?', select 'No'
Repeat the process for the remaining adresses adding in turn bit files for 3: CP system, 4: SumEt crate, 5: SumET system, 6: Jet Crate, 7: Jet System.
After all bit Files have been added to the collection double-click 'Generate File...' in the 'iMPACT Processes' pane
Click 'OK' in the 'ACE File Generation Option' pop-up. iMPACT will now loop over the files and create CF file system - this takes several minutes.
On completion a blue box with a message 'Generate Succeeded' should appear - you are done quit iMPACT