TrackBuilder support

[aehart]

This PR introduces support for the TrackBuilder.

In the current wiring, the TrackBuilder writes to a single TrackFit memory, while the actual HLS module streams its output as a track word and several stub words. To deal with this, after parsing the wires file, all TrackFit memories are replaced with the appropriate streams by the split_track_fit_streams function in TrackletGraph.py.

The top module for the reduced config pattern recognition can now be generated and seems plausible, though the modules involved will need to be modified before it can be synthesized: ~https://github.com/aehart/firmware-hls/blob/bf5ad0a74da90847e2083a26d918b95843be2cc8/IntegrationTests/ReducedConfigPR/hdl/SectorProcessor.vhd~ ~https://github.com/aehart/firmware-hls/blob/0c31cdf5f0b518d55107688ec437b6797ef6d72b/IntegrationTests/ReducedConfigPR/hdl/SectorProcessor.vhd~ https://github.com/aehart/firmware-hls/blob/f6de97c5781a955ea8db551223bd9a72c4924748/IntegrationTests/ReducedConfigPR/hdl/SectorProcessor.vhd Also, this top module can only be generated after manually removing the PD processing module from the wiring, although this is very easy to do.

Edit: The above top module was generated with the following recipe:

git clone -b track_builder https://github.com/aehart/project_generation_scripts.git
git clone https://github.com/cms-L1TK/firmware-hls.git

cd firmware-hls/emData/
./download.sh -t
cd ../../project_generation_scripts/
cp ../firmware-hls/emData/LUTs/*.dat ./

./makeReducedConfig.py -n True
sed -i "s/ PD\.trackin//g" reduced_wires.dat # remove output of TF_L1L2
sed -i '$d' reduced_wires.dat                # remove CT_L1L2 wires
sed -i '$d' reduced_processingmodules.dat    # remove PurgeDuplicates
sed -i '$d' reduced_memorymodules.dat        # remove CleanTrack

# SectorProcessor.vhd
./generator_hdl.py -w reduced_wires.dat -p reduced_processingmodules.dat -m reduced_memorymodules.dat
# SectorProcessorFull.vhd
./generator_hdl.py -w reduced_wires.dat -p reduced_processingmodules.dat -m reduced_memorymodules.dat -x

[tomalin]

In the explanatory notes for this PR, please say which ./generator_hdl.py arguments should be used to test this new code?

[aehart]

In the explanatory notes for this PR, please say which ./generator_hdl.py arguments should be used to test this new code?

I just added a recipe for generating the top module for the reduced config to the initial comment for the PR.

[tomalin]

In the explanatory notes for this PR, please say which ./generator_hdl.py arguments should be used to test this new code?

I just added a recipe for generating the top module for the reduced config to the initial comment for the PR.

In the recipe, the variable $d is not defined?

[tomalin]

Please check that options --uut and --mut of generate_hdl.py work for chains that include the TrackBuilder. e.g. It is not listed as a possible "choice" for the --mut argument at https://github.com/aehart/project_generation_scripts/blob/track_builder/generator_hdl.py#L362 .

[aehart]

In the explanatory notes for this PR, please say which ./generator_hdl.py arguments should be used to test this new code?

I just added a recipe for generating the top module for the reduced config to the initial comment for the PR.

In the recipe, the variable $d is not defined?

Each of those sed commands simply removes the last line of the file. The recipe works in every shell I tested. Note that the single quotes around '$d' are necessary, and double quotes will not work.

[aehart]

Please check that options --uut and --mut of generate_hdl.py work for chains that include the TrackBuilder. e.g. It is not listed as a possible "choice" for the --mut argument at https://github.com/aehart/project_generation_scripts/blob/track_builder/generator_hdl.py#L362 .

The --uut option seems to work out of the box and the output seems sensible. I also added FT as a possible choice for the --mut argument, and as a test, I verified that the following two commands produce an identical SectorProcessor.vhd:

./generator_hdl.py -w reduced_wires.dat -p reduced_processingmodules.dat -m reduced_memorymodules.dat --uut FT_L1L2 -u 4 -d 0
./generator_hdl.py -w reduced_wires.dat -p reduced_processingmodules.dat -m reduced_memorymodules.dat --mut FT -u 4 -d 0

So the options seem to be working with the TrackBuilder.

[tomalin]

Please check that options --uut and --mut of generate_hdl.py work for chains that include the TrackBuilder. e.g. It is not listed as a possible "choice" for the --mut argument at https://github.com/aehart/project_generation_scripts/blob/track_builder/generator_hdl.py#L362 .

The --uut option seems to work out of the box and the output seems sensible. I also added FT as a possible choice for the --mut argument, and as a test, I verified that the following two commands produce an identical SectorProcessor.vhd:

./generator_hdl.py -w reduced_wires.dat -p reduced_processingmodules.dat -m reduced_memorymodules.dat --uut FT_L1L2 -u 4 -d 0
./generator_hdl.py -w reduced_wires.dat -p reduced_processingmodules.dat -m reduced_memorymodules.dat --mut FT -u 4 -d 0

So the options seem to be working with the TrackBuilder.

The command "./generator_hdl.py -w reduced_wires.dat -p reduced_processingmodules.dat -m reduced_memorymodules.dat --uut FT_L1L2 -u 4 -d 0" gives me error "matchArgPortNames_TB: Unknown argument name diskFullMatches[]", which I assume is because function matchArgPortNames_TB() https://github.com/aehart/project_generation_scripts/blob/track_builder/WriteHDLUtils.py#L746 explains how to use the barrelFulLMatches arg in the top-level TB HLS https://github.com/cms-L1TK/firmware-hls/blob/master/TrackletAlgorithm/TrackBuilderTop.h#L10 , but not how to use the diskFullMatches arg?

[aehart]

Please check that options --uut and --mut of generate_hdl.py work for chains that include the TrackBuilder. e.g. It is not listed as a possible "choice" for the --mut argument at https://github.com/aehart/project_generation_scripts/blob/track_builder/generator_hdl.py#L362 .

The --uut option seems to work out of the box and the output seems sensible. I also added FT as a possible choice for the --mut argument, and as a test, I verified that the following two commands produce an identical SectorProcessor.vhd:

./generator_hdl.py -w reduced_wires.dat -p reduced_processingmodules.dat -m reduced_memorymodules.dat --uut FT_L1L2 -u 4 -d 0
./generator_hdl.py -w reduced_wires.dat -p reduced_processingmodules.dat -m reduced_memorymodules.dat --mut FT -u 4 -d 0

So the options seem to be working with the TrackBuilder.

The command "./generator_hdl.py -w reduced_wires.dat -p reduced_processingmodules.dat -m reduced_memorymodules.dat --uut FT_L1L2 -u 4 -d 0" gives me error "matchArgPortNames_TB: Unknown argument name diskFullMatches[]", which I assume is because function matchArgPortNames_TB() https://github.com/aehart/project_generation_scripts/blob/track_builder/WriteHDLUtils.py#L746 explains how to use the barrelFulLMatches arg in the top-level TB HLS https://github.com/cms-L1TK/firmware-hls/blob/master/TrackletAlgorithm/TrackBuilderTop.h#L10 , but not how to use the diskFullMatches arg?

You're right. I had forgotten about diskFullMatches because there aren't any matches in the disks in the reduced configuration.

I have updated WriteHDLUtils.py to correctly handle diskFullMatches. The output files are identical, but the warning has gone away.

[tomalin]

The file memUtil_pkg.vhd produced by "./generator_hdl.py --uut FT_L1L2 -u 0 -d 0 -x " defines type "t_arr_TW_84_NENT", but the this type is never used. (Though perhaps it will be needed in the test-bench?). And the type "t_arr1_7b" on which it is based isn't defined in tf_pkg.vhd in the HLS repo. In addition the ports of SectorProcessorFull.vhd have signal names that don't quite follow the convention elsewhere. Any signal that is of type std_logic_vector should have "V" in its name. And any signal that is a (multi-dimensional) array, should have AA" etc. in its name, with number of "A" equal to the dimension of the array. Hence DW_49_stream_A_full_neg, DW_49_stream_A_write etc.

[tomalin]

The command "./generator_hdl.py --uut FT_L1L2 -u 4 -d 0" crashes, though this is apparently a bug in the TrackletCalculator script, so needn't delay this PR.

[aehart]

The file memUtil_pkg.vhd produced by "./generator_hdl.py --uut FT_L1L2 -u 0 -d 0 -x " defines type "t_arr_TW_84_NENT", but the this type is never used. (Though perhaps it will be needed in the test-bench?). And the type "t_arr1_7b" on which it is based isn't defined in tf_pkg.vhd in the HLS repo.

I don't believe the *_ADDR and *_NENT types are needed, even in the test bench, so I disabled their creation as is done for the DTC links.

In addition the ports of SectorProcessorFull.vhd have signal names that don't quite follow the convention elsewhere. Any signal that is of type std_logic_vector should have "V" in its name. And any signal that is a (multi-dimensional) array, should have AA" etc. in its name, with number of "A" equal to the dimension of the array. Hence DW_49_stream_A_full_neg, DW_49_stream_A_write etc.

Thank you for explaining the convention, which was mysterious to me. I updated the signal names to follow it.

Also, now that #28 is merged, I rebased and added nentries ports for TPAR memories if at the end of the chain. As with the AS and AP memories, these ports aren't usually needed because the entries are not read sequentially by the TrackBuilder.

[tomalin]

The command "./generator_hdl.py --uut FT_L1L2 -u 1 -d 0" produces SectorProcessor.vhd that writes its "TrackWord" output via ports:

• TW_84_stream_AV_din : in
• TW_84_stream_A_full_neg : in
• TW_84_stream_A_write : out

The first of these maps to port "trackWord_V_din" of the TB HLS module, which the HLS synth report says is an output port. So should we replace "in" with "out"?

[aehart]

The command "./generator_hdl.py --uut FT_L1L2 -u 1 -d 0" produces SectorProcessor.vhd that writes its "TrackWord" output via ports:

* TW_84_stream_AV_din : in

* TW_84_stream_A_full_neg   : in

* TW_84_stream_A_write  : out

The first of these maps to port "trackWord_V_din" of the TB HLS module, which the HLS synth report says is an output port. So should we replace "in" with "out"?

Yes, you're right. I have just fixed it.