Working with version control tools can be a challenging task. There are plenty of tutorials how to do it properly, and there are many methodologies. Most of them deal mainly with which files to save, how to organize the folders properly, etc. Xilinx itself explains 3 methods here (minimal , recommended and maximal).
Nonetheless, when the common user start working on a project, usually it is well organized and the methodology of how to define the folders properly was already carried out long time ago, before he/she has joined the team, thus over-looked.
When we want to start using a revision control tool from scratch, all project folders should be organized in such manner that checking them in & out would be an easy task. We would not want to spend time on tedious beyond-comparing them, and struggling to find the exact path of the checked-in files in each compared project.
What if, like in my case, I started working on a project as a lone wolf, and later on, other people jumped in?
In that case, reality slapped me in the face, and I had to do some initial work before using Bitbucket. Well, say goodbye to lone wolf, and hello A-team.
When working with a regular Vivado project, all files are organized in local repository folders. The directory tree is rather cumbersome, and I admit that it’s not uncommon that I still haven’t found what I’m looking for, when looking for a specific file. The task becomes more challenging when I import files from different project & folders, source some pre-written tcl’s, etc. etc., and I can go on & on. The result will be a file path as long as the COVID-19 long haul.
Stage I — order! order!
The first thing we should do is to organize a set of folders for the version control. You can go over Xilinx tutorial, already mentioned here, and see their recommendation:
Personally, I prefer the following:
I’ll start with an mkdir of a ‘src’ directory, and I’ll create some more folders in it, each one will be in charge of different files. The src will be backed up regularly, both in zip, and to version control. I’ll go over it:
sdk — if working with Microblaze/Zynq, all sdk files will reside here.
xdc — different xdc files. Tip for successful and tidy work is to divide the xdc according to its goals; physical (for pinout), timing (for timing constraints) and debug (for ila attributes).
rtl — all vhd/v files, divided to folders per their functionalities in your project.
repo — for storing all IP’s (you can read it in UG1119).
bd — all block design files
sim — simulation files
ip — my own IP’s. Pretty much same as repo.
scripts — all created tcl files. For example, the write_project_tcl, which I’ll go over later, is stored here.
Stage II—moving from Internal To External
Initially, my project was built using the default Xilinx directory tree. Now, here comes the tricky part. I want to change it, and make Vivado take all files from the newly created, currently empty, remote location.
When we start a project from scratch, this is a non-issue. We just change the File location from <local to Project> to whatever remote location we want:
But now, my project is already full with dozens of files, all local. How the earth can I make Vivado change its reference?
I’ll show that on a small project. The solution is divided to 2 parts; regular files and BD files.
We’ll move all files from its current local repository to the remote location and we’ll do it without ‘informing’ Vivado. That is, in our file explorer (I’m working with MobaXterm SSH to Kubuntu).
- I’ll move the files to the new ‘src’ location. This will obviously cause Vivado to get confused since it will not find the files. This is exactly what I want to happen.
Before the change:
And after moving the file, using the following command:
mv /export/home/xilinx_projects/project_1_/project_1_.srcs/sources_1/imports/top/led_blk.vhd src/rtl/led_block/.
2. Next I’ll tell Vivado where the files are located at. I can do it one file at a time (right click on specific file and ‘Add sources’)
This is vital to Uncheck the copy sources to project, as this is the whole idea, that Vivado will use the files in its remote location and not import them to the original project tree.
After relocating the file, the reference to the file will look like this:
Which is exactly what I wanted.
Doing this for all related files, and you’re almost done. I’m saying ‘almost’ as we have a bit more challenging task to overcome, and this relates the BD files. This is where things gets more complicated and it is due to 2 issues: the BD itself and the wrapper file.
Handling BD files
The default is the <local to project> option and we have to take care of the wrapper file.
- We’ll need to create an additional BD and point Vivado to the ‘src’ remote location:
We’ll need to give it a different name, since we can’t have 2 BD’s with the same name:
2. copy-past the original BD to the new BD. Now we have 2 BD’s with the same design:
3. create a wrapper file to the new BD (‘design_tmp’) and check the ‘copy the generated wrapper to allow user edits’
Now we have 2 identical BD’s with wrapper files. This gets interesting, since even though the wrapper file is located locally (as seen below), it is also already saved at the remote ‘src/bd’ folder.
3. delete the created wrapper file and add it again, but this time, use the ‘Add sources’ option, and not create wrapper option. Choose the remote located file and validate the ‘copy sources into project’ is unchecked.
And that’s it. You can see the new chosen file is located at the src remote folder:
4. we can now also remove the first ‘design top wrapper’ from the project (also from disk), but remember to do it carefully, since the led_blk file is already located at the the remote src folder, so removing all of the ‘design_top_wrapper’ will also delete this file from ‘src’ folder.
So, we now have a migrated remotely project, all located at ‘src’ folder, and we’re good to go to version control tools:
Are we off the hook yet?
Hmm… not so fast.
we have 2 more issues to handle, zipping and ‘write bd tcl’.
write project tcl
This command is a very common and handy one in order to save the BD components into a tcl for a later building it again from scratch.
We just have to remember to un-check all boxes, and also save it under ‘script’ folder inside src:
Keeping the ‘copy sources to new project’ checked will guide Vivado to place all remotely located files to be placed locally in the next time you recreate the project (using source led_design.tcl), which obviously will ruin all the hard work we’ve done so fat, so, better remove this checkbox.
Lastly, remember to zip it!
Then you’ll have a full project, inside the remote location:
zip -r src_led.zip src
Some notes to remember:
- using ‘save as…’ option is not a good idea. It will cause Vivado to take all remote lcoated sources files and place it in the local repository folder structure.
- In case we want to recreate the folder under different name, we can source the project tcl, and the whole project will be built from scratch where the files are referenced to the remote location.
- when we want to create a new project, remotely located, we need to copy-paste the original src folder to a new one (in case we want to make some changes, and want to keep the original one unchanged).
- We need to change 2 lines in the script, to guide Vivado to take the remotely files from a new ‘src’ remote location:
And that is it!