Keeping your design files organized

Men marry women wishing they will never change, but they do.Women marry men wishing they will be able to change them, but they don’t.

When I was young, even during my University studies, I was a real disaster in anything related to order. My room was always a mess. Whenever my mother or any other would try to change my ways (even a little bit), I would say what many like me love to say:

– “In the disorder, I know where everything is. When my mother makes some order, I can’t find anything”.

And to demonstrate that the half-joke at the beginning of this article is not true, I must say that I changed a lot since I married. My home won’t appear in a decoration magazine, but it is not close at all to my young-days’ complete-mess room.



The other reason I have to train me all the time to be a more tidy person is that I work in FPGA design. So if you are rolling your eyes thinking that order has nothing to do with design, and I’d better publish some interesting VHDL tips instead of all this “be tidy” nonsense… hang with me a bit more, and I hope I can convince you. If, on the other hand, you are rolling your eyes because for you it is OBVIOUS that order and method are needed… keep reading, maybe you can learn a pair of tips to improve your methodology.

Also read: Pseudo random generator tutorial in VHDL (Part 1/3)


Keeping your files organizedTo keep your files organized, the basic method is really very simple. You make a directory tree with categories for each one of the files types needed for your design.

The above screenshot is an example of how I organize projects in my hard disk. The categories are not mandatory, you may want more or less.

[*=left]docs– documents, pictures, specs, datasheets
[*=left]hdl– all synthesizable HDL source files (VHDL and/or Verilog). Of course, as the design grows, this will be divided in sub-directories, one for each module. And not only one for each module, but other “special directories” as well, for example, one for common files and packages, another one for Altera IP’s, etc.
[*=left]matlab– for formal verification of the design
[*=left]quartus– here I synthesize the design using Altera tools (adapt it to your preferred manufacturer)
[*=left]sim– Simulations. Here I configure Modelsim to drop all its files
[*=left]tb– Testbench files used together with Modelsim, but that will not be included in synthesis

The most important target to achieve is to update your files in a single placeI don’t change any source that is part of the design in no place other than the ‘hdl’ directory. When I setup the simulation, I instruct Modelsim to take its source files from hdl. Quartus is also instructed to take the files from there. And I have a single point of update. If you don’t do something like this, try it. It will save you a lot of headaches.

The second target to achieve is to keep key directories cleanQuartus, Modelsim and other design tools tend to produce lots of bulky files. If you let those tools drop their files together with your source files, soon maintaining your design will become a nightmare.

The third target to achieve is ease of version control and backupIf you separate your folders, when you make backups (and you should, frequently) it is easy to separate the relatively small source files from the bulky reports from Synthesis or waveforms from simulation. These days there is no excuse at all not to make many backups, as many as you can, using disk-on-key, the cloud and version management tools like Clear Case, SVN or GIT.

Each time you make a new backup, give it a new number and keep a read.me file at the root of the backup folder stating the date of the backup and major features of this version/bugs solved/bugs pending and any other useful information. Version management tools usually provide logs/text for version tracking. Personally I find easier to track my major version features and to-dos on the read.me file, but you may find easier to use the features of your version management tool.

As good as it can be to use your own version control tool, or a commercial one, I think that it is very important to keep a complete backup for any customer released versions (including compile file results and reports). You will need this information for sure. Many times you will need it many years in the future, when you have almost forgot anything about the project.

You have to document everything so a stranger will be able to maintain your code. Specially since that stranger may very well be you yourself, in years to come.

Keeping track of your tasksCall me old. I still have and use design notebooks. Each time I go to a meeting I write down everything I can. I tend to forget a lot of things unless I write them down. I also write date, project, and main points and decisions of the meeting. I know, the organizer should send a meeting summary. So he/she should. In my country, many times that simply doesn’t happen or if it happens, it has a lot of information holes on it. When my boss or my client asks for something, I add it to a note or to my notebook. When I am back at my computer, I update my TO DO list. I have one list for each projects, with three or four columns:

[*=left]Title,
[*=left]Description,
[*=left]Done, and
[*=left]Remarks

When I complete a task I mark the third column, which in itself is a nice thing to do. Nothing like dropping some weight from your shoulders. And your boss/client will love not having to ask you for a specific task to complete, again and again.

When I published this article in LinkedIn, one designer commented that he uses a ticketing system not only for bug management but also for task management.

Now is your turn. I would love to hear your tips to keep the job done, your files organized, and your day productive.

My blog:FPGA Site