Source control is for everyone -

Source control is for everyone


We've all been told that we should backup our work when using a computer. Everyone accepts that we must keep multiple copies of important files, and most businesses automate the process. When it comes to programming embedded systems, a version control system should be as mandatory as backing up files. At my company, the programmers are required to use a source-control system but the programmable-logic designers don't even have accounts on the source-control server. Leaving out the hardware engineers makes no sense, especially considering that all of my recent projects included programmable logic that could be updated in the field as easily as the software.

In this article, I'll briefly describe source control, outline its benefits when used for both hardware and software designs, and show you how to add hardware projects onto a source-control system.

Source control 101
Source-control systems record all file changes, with comments, in a project. If the file is a text file, the system saves only the changes, which allows the source-control system to recreate any version of the file. The versions of each file are stored in a repository that can either be stored locally (a file-based system ) or remotely (client/server systems ). A useful feature of source control is the managed merge process, which allows two versions of a file to be merged automatically, although sometimes minor manual help is needed.

Several products are available for source control. Some are commercial, such as IBM Rational's Clearcase or Microsoft's Visual SourceSafe; others are open source, such as CVS (Concurrent Versions System) and Subversion.

Benefits of source control
Regardless of the source-control system you use, you'll always gain several benefits when using such a system. One of the first advantages is the ability to identify differences across versions of a file. Suppose a once-functioning program feature no longer works after changes are made to improve the comments or add a feature. Comparing the changes between the current file and the previous known-good version will reduce the time required to locate and fix the error. Figure 1 illustrates how file differences might be shown.

Figure 1: Example difference
Screen shot made using winmerge

View the full image size.

Because the repository system is built into the source-control system, all of the source files can be shared among everyone working on a project. This shared access can improve a team's ability to reuse code others have written and eases the burden of the peer-review process. Repositories stored centrally also make it convenient to back up all the source files for a project.

Another advantage to source control is the ability to “branch” file versions. This feature can be useful for making bug fixes when projects have already been released to the field and the next build of the project is in development. Figure 2 depicts the branches necessary for a bug fix during new development. Point A is the initial field release and the start of new development. When the bug was found the “bug fix” branch is created at Point B. After the bug is fixed, the changes are merged back to the Main Line and to the New Project branch (Point C). After the New Project is ready for release it's merged back to the Main Line (Point D). Without version control this process is manual and requires that bug fixes be tracked and painstakingly added to both the released version of the project and the next branch. Using a source-control system automates the process of retrieving the released version of the files and merging the changes into the current version.

View the full image size.

Branching also benefits parallel development. If several people are working on the same code, an integration branch can be created. When any party has new working code, it can be merged to the integration branch where all parties can use the change. Testing ideas is simplified when using branches; the changes can be made without fear of losing previous work, even if the idea doesn't work as desired.

Hardware design benefits
If the development cycle you're familiar with is anything like the ones I've experienced you've routinely seen whole project directories copied to track major changes. This is the poor man's version of source control. It's obviously a manual process, which makes it easy to forget to make–and very difficult to find–changes in the source. So if this process sounds familiar to you, you'll benefit from an automated source-control system.

Centralizing the source code from the beginning of a project will allow both software and hardware developers to debug their code more efficiently. Many times in my own debugging I've suspected that the hardware wasn't doing what was expected. Without access to the source code I have two options. I can involve the hardware developer and we can work through the problem together, or I can keep testing until I fix the software problem or convince myself that something's wrong with the hardware. If I had access to the hardware-design code I could look through that code and determine that I'd either misunderstood the hardware design, the hardware was wrong, or the software was wrong. This type of debugging is equivalent to looking through a schematic to develop code. Since fewer wires are available to probe, the software engineer needs more access to either the hardware developer or the source code. Giving the software and hardware engineers equal access is like increasing the information in the data sheet for the hardware.

With source control the hardware modules created for one project can be more easily used in multiple projects. The other benefit to sharing modules from a single location is that a bug fix made to a module will fix all of the projects using that module–there's no need to make the same change in multiple places.

With more experience using source-control for both hardware and software source files, you can extend the build system to build and release hardware as well. Current hardware build times are longer than software build times, which means it's likely that the time required to build hardware may limit this option. However build machines are becoming faster such that the time required will be manageable. It's also possible to set up the build to only build the hardware if changes to the source were actually made. If these obstacles are overcome building the hardware with the same build system as software ensures that building a bug-fix release will only require the build system to work; no longer will finding a computer that may still have the software installed be required (since it will be on the build system).

The other long-term benefit to using source control is the potential growth of hardware/software codevelopment tools. Taking the source of a hardware design to create the header file for a specific hardware module becomes convenient and therefore possible. Centrally locating the source for both hardware and software designs greatly increases the likelihood of creating and using these tools.

Getting started
Getting hardware projects up on source control might seem overwhelming, so if you're uncomfortable placing all the input files for a project under source control, you might start by placing just the HDL modules under source control; HDL modules are the most natural choice and starting with them will still deliver most of the benefits of source control. Also, software engineers who are familiar with source control can help set up the system. Since I haven't used every hardware design tool I don't know if it's always possible to have the hardware modules located separately from the rest of the files of a project. If separate file locations are not possible, your only option will be to place the entire project into source control. This task isn't too complicated and the rewards will be worth it.

When you're ready to place your entire project under source control you'll need to find all the input files for your tools. For this to work properly, the build process can't be allowed to write to the input files. Two problems are caused if a build process is permitted to write its input files. First, the source-control system will want the input files to be read-only to ensure no changes are made (since it must keep track of changes). Second, if an automated build process is used the output of one stage of the process might make the build tool believe that the current stage needs to be rebuilt, causing an infinite loop of the build.

A couple of options are available for finding a project's input files. If you're using a development tool that is aware of source control, the process may be as simple as reading the documentation and following the directions for placing the project in source control. If you aren't that lucky you might try searching the Internet for what others have done with the tool you're using. If neither of these options work for you, you can create a test project and set up everything in the project to be built but don't actually build the project. Instead, save your work and exit the tool. All the files created during the process are likely input files that should be under source control. Be sure to check for hidden files as well; some vendors want to ensure that users don't edit their configuration files manually so they create hidden files.

After all of the input files are under source control, the next step will depend on the source-control system you're using. If you use Clearcase, only checkout files need to be modified when making changes. This includes making changes to project configuration as well as HDL files.

When you're ready to release a build to the software team for testing, I suggest placing the final output file (such as the file needed for configuring an FPGA or any other files needed by the software team) under source control. There are two methods for putting the output file into source control. One option is to put the output file directly in source control and change the version of the file with each release of the hardware. The other option is to change the name of the file to something unique for each release and put the uniquely named file into source control. I prefer to put each release file into source control as a unique file because it makes it easier to see the releases without using the source-control system to find a specific version of the file. It's especially important to put the output file in source control if the hardware build process takes a while or is only available on a specific machine. If you work in a large team, I recommend a pilot program for using source control. The pilot program will enable a small development team to document and test the source-control process.

On the same
Programmable logic devices are getting larger and more complex every day. FPGAs are no longer just the glue for several ICs on a board, they're complete systems that are sometimes upgraded in the field. The design process for these FPGAs mirrors software design and the tools of the software development team should be used in the development of FPGAs as well. A source-control system is critical for software development, for tracking source changes and releases. Using source control for hardware adds the benefit of tracking hardware designs and codevelopment of hardware and software. The use of source control for any source code (whether it be C, C++, Java, VHDL, Verilog, and so forth) should be considered as important as backing up files. None of my peers who have reaped the benefits of source control would willingly give it up.

Michael Jansen has been designing hardware and firmware for embedded systems for the last six years. He has a BSEE from Kansas State University and an MSEE from Marquette University. Michael can be reached at .

Reader Response

While I cannot fault your article about putting hardware designs into version control as far as your intent goes, I feel that there is yet a fair amount that can be said about the subject. To begin with, not all programmable logic is designed with HDLs of some description or another. And even those that are sometimes include a “mixed mode” of schmatics and HDL. Usually the higher levels of the architecture are done schmatically while the modules are in HDL. This is because no one can look at a few thousand lines of any kind of “code” and have any kind of instintual feel for what the device does or how it is organized. Yet the graphical hierarchical schmatic can help the viewer to get a fell for what is there as long as it is done in a thoughtfull way.

What has any of this to do with version control? Well, most version control systems think that all input files are textual. In most of the hardware “IDEs” that is not the case for all files since many of the files are kept in a format other than text (binary, proprietary). Even if no one ever drew a schematic again this issue would remain because of issues such as floorplanning which is done graphically and stored non-textually, probably for reasons of file size or propritary IP protection. Furthermore, they all produce intermeadiate files of various kinds that convert whatever form of design content there may be into a proprietary “place and route” format for final creation of the programming files. The process bears only a superficial resemblance to producing software, and attempts I have made to use version control software have been frustrating. On the up side however, some (if not all by now) vendors have recognized the need and have incorporated at least a rudimentary form of source control into their IDEs. This is where the effort to establish version control must be made, not at the user level. Still, all is not rosy in hardware version control land because a lot of the hardware can be outside of the programmable logic realm, out there on the PCB. Simple circuits out there can transform what look like ones and zeros into something that looks like a heartbeat or some other desired waveshape, transform the power level, or some other non software looking thing. No matter how digital it starts out, its gotta look like rubber when it hits the road. I think that there is very little of that design effort that has any form of version control although it could certainly use it.

-Don McCallum
Sr. Electronics Engineer
Rancho Cordova, CA

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.