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 order.

Keeping your files organized

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

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.

docs – documents, pictures, specs, datasheets

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 some other, one for common files and packages for all modules, one for Altera IP’s, etc.

matlab – for formal verification of the design

quartus – here I synthesize the design using Altera tools (adapt to your preferred manufacturer)

sim – Simulations. Here I configure Modelsim to drop all its files

tb – Testbench files used together with Modelsim

The most important target to achieve is to update your files in a single place. 

I 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 clean.

Quartus, 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 backup.

If 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 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 file, but you may find easier to use the features of your version management tool.

Keeping track of your tasks

Call 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.

  • Title,
  • Description,
  • Done, and
  • 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.

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

6 thoughts on “Keeping your design files organized

  1. Totally agree ! In addition, I would suggest to use a git repository. This is quite useful! Remember to exclude the generated files from quartus and modelsim 😉

  2. I have a similar hierarchy structure folder.
    In addition to this, I use tcl scripts to keep a clean and clear project. If you want I could show you my design

Leave a Reply