MicroZed Chronicles: Working with Source Control
Of all the subjects I have covered in this blog over the years, working with source control is one which I should perhaps of addressed…
Of all the subjects I have covered in this blog over the years, working with source control is one which I should perhaps of addressed earlier.
Source control is important in any development it enables:
- Sharing of the code base between developers
- Creation of baselines — The ability to know exactly the delivered functionality for a specified baseline.
- Tracks code changes — Each time a file is updated / committed a explanation is need as to the changes made to it and why.
- Ability to roll back — If necessary, the ability to recreate previous baselines from the repository can be very useful.
- Redundancy — The design files are no longer stored on a single computer instead they are committed to a source control system.
When we work with FPGA and heterogeneous SoC devices, we have to address source control both for the programmable logic and for the resultant SW application.
In this blog, we are going to take a look at how I work with change control for both Vivado and SDK.
Before we examine the details, there are some basic rules for working with Vivado and source control that we should follow:
- For custom IP use your own repository external to the project
- Work with TCL files and scripts
- Do not copy sources into the project keep them external
Let’s first take a look at how we can handle custom IP. To ensure we can reuse the custom IP cores across several projects, we should use a IP repository. We can then add this repository into our Vivado project under the settings menu.
This repository is the first consideration for source control using one allows us to keep most of the code external to the Vivado project. Each IP in the repository should be within its own directory and will contain a number of files including HDL, XML, TCL, C,C++, XCI files. All of these files should be added to the source control. Remember, if you use custom IP definitions (you really should be) then these also need to be added to the repository.
A good example of an IP repository is the Avnet HDL repository.
With our IP source controlled, we now need to consider how we address the Vivado project.
The simplest way is to create a TCL build script that creates a project, pulls together the source files, and performs the build. For simple projects you can do this in a surprisingly small number of lines depending upon the number of source files.
However with more complex projects, we might want to work with IPI integrator and create a block diagram(s) — this is especially true if we work with the Zynq or Zynq MPSoC.
The incorrect way to do source control in this instance is to source control the block diagram, the better way is to work with TCL scripts.
Rather helpfully, we do not have to write the TCL script from scratch. We can use the write_project_tcl command. This command will output a comprehensive TCL project description.
We can then add this file to our chosen source control tool and use it to recreate the project as necessary.
Let’s take a look at how we can do this using a simple example.
I have created a project which uses the Zynq in a block diagram, on my GitHub. I have also created a new repository called Souce_control_example.
For this example, I am initially going to add the necessary files and then show how this can be cloned and used to recreate the project as required.
Within the example Vivado project TCL console I issue the command:
write_project_tcl scs_example.tcl
This writes out the configuration of the project into a TCL file called scs_example.tcl.
Once this command completes, you will see a warning in the TCL console if there are any design files included within the design.
We should keep most design files external to the project as I said. However, the top level design wrapper which describes the block diagram will be included within the project.
To be able to recreate the project we also need to include these files in the repository.
The files we need to include are identified in the header of the TCL file just created.
In this example, you will see the project wrapper and the constraints file.
The TCL file is also be generated to pick up the files from those paths, when it is recreated.
It is simpler to edit the file such that the TCL script looks for any included files in the origin directory. Doing so is a fairly simple edit to make, as shown below for the wrapper:
With this completed, we can then up load the files to our chosen git repository.
With the files safely stored in the repository, we are now in position to clone the repository and rebuild the project.
To clone the project to a different directory on my PC I used a gitbash client.
Within the cloned directory, you will see the three files that are required to recreate the project.
The next step is to open Vivado and and change the directory in the TCL console to the directory just cloned.
Once we are in that directory, we can source the TCL file and wait a few seconds while the project is recreated.
After the project is recreated, we need to then re-run the generation of the bit stream. But you will see the project has been recreated successfully; of course throughout the development process, you need to keep the project TCL description up to date as we make changes to the block design.
You may also want to start adding to source control files such as IP configurations, debug files, hardware descriptions, and design specific architectures as the project progresses.
With the Vivado design safely configured, we now need to consider the software source code configuration.
Within the project we just recreated, export the hardware with the bit file and launch SDK.
Using SDK create a new project and bsp, the simple hello world example will be fine.
Now we have a application project, we are in a position where we can add files to source control if we desire.
We do this by right clicking on the source directory and selecting Team.
Under the team sub menu, if you select Commit you can select the files that can be committed to the repository.
Selecting commit will open a dialog that enables you to add select file you wish to commit and any commit message as to the reasons for the update.
To demonstrate this, I committed the helloworld.c file.
When you click on Commit and Push, SDK will push to the git repository. If necessary SDK will ask for User and Password details for the repository.
Provided these are acceptable, you will then see a Push Confirmation prior to the push which shows the expected push results. If there are any issues, it is at this stage we can go back and address them.
Clicking Finish will then show the final result of the Push.
We can now check this has been pushed correctly on the GitHub page, and of course other users of the repository can then pull down any changes.
As we make changes to the source code, we will see indications in SDK that the file needs to be pushed. A > marker will appear before the file name and the directory name.
If we want to pull down changes from the repository, we can also do so using the Team menu.
So there you have it, how to work with source control for both Vivado and SDK.
See My FPGA / SoC Projects: Adam Taylor on Hackster.io
Get the Code: ATaylorCEngFIET (Adam Taylor)
Access the MicroZed Chronicles Archives with over 250 articles on the Zynq / Zynq MpSoC updated weekly at MicroZed Chronicles.