Give Files in Your IC Design Flow Useful Names

When a user wants chip design data, a script or a log file,how do they find it? They use file and directory names. As an IC design flow architect, proper file naming is the most important thing you can do to guide your users to the files they need. By just looking at the path and name of any file, a user should be able to determine:

• Design name
• File format
• Step that created it, and therefore the tool that created it
• operating conditions if pertinent

This is one of a series of articles on simple, specific techniques that will make your chip design flow easy to use. In this installment, I will explain how to give helpful names to files and directories. Other articles include,

• Apply the Scientific Method to IC Design Flow
• Write Effective Error Messages
• Properly Name Log Files for EDA Tools
• Control Your IC Design Flow
  

Choose a Step Name and Use It for Everything

Choose a descriptive name for every step of your flow. Users will type this name a lot, so keep it short, use lower case letters, and maybe one capital letter. Generally a step name will be a verb. Use this name for everything related to the step:

• Script
• Log file
• Output database and reports
• Makefile target
• Variable names
• Name used in project management software, such as Bugzilla

When the step name alone is insufficient, append more information, for example, placeMin.rpt, placeTyp.rpt, placeMax.rpt. This way, all files related to step place appear together when listed alphabetically.

See also the related topic of chip design flow variable naming conventions.

One Design Per Directory

Many flow designers start out thinking that it might be useful to allow multiple physical hierarchical designs to share a working directory. It is not useful, so each design in the physical hierarchy should have its own directory.

There is no need to organize the working directories into a hierarchy of directories that match the chip hierarchy. Put the working directories wherever they make sense in your work flow.

Since there is only one design, use the design name for the:

• Design directory name
• Database library name
• Output files containing the completed design:
  • Design name in the database. Use the most ordinary view name. For example, the completed layout for design blockHead should be saved to OpenAccess as blockHead/blockHead/layout, or in Milkyway as blockHead.CEL.in library blockHead.
  • GDSII file, like blockHead.gds
  • Text format files, like blockHead.v, blockHead.def, and blockHead.lef

Otherwise, use the design name sparingly. The design directory is named after the design, so every file path already contains the design name.

A Working Directory for Each Tool

Within the directory for a design, create a directory for each EDA tool used. When using a tool, cd to its directory and then start the tool. While running the tool, do not change the working directory.

I have seen flows organized with the tool directory above and the design directory within (toolName/designName). It’s possible, but it does not work as crisply as designName/toolName.

Use Relative Paths, Avoid Symbolic Links

Relative paths allow your run directory to be moved or copied freely. Relative paths are shorter, and therefore easy to read.

Absolute path names do have their place. It is reasonable to use a fully qualified path to things that are separate from the current design:

• Libraries, technology files, and other input data
• Software applications and the design flow

Even so, it may be best to avoid directly specifying the path to these things, and take a more sophisticated approach to managing your design environment, such as using the modules package.

Do not use symbolic links as a part of your flow. Symbolic links are a sneaky way to make files appear to be somewhere they are not. In a design flow, you want straightforward, not sneaky. Use a variable instead of a symbolic link.

Use Names Compatible with Verilog

You will use design names as file and directory names, and vice versa. The most restrictive name space used in IC design is Verilog, so obey Verilog naming rules when choosing directory names and file base names. It’s simple:

• Use only alphanumeric characters and _
• The first character must be a letter

This way, file names can match the names of design objects without complicated escape sequences. These rules apply to the base name (as in baseName.ext), not the file extension name.

Name for Alphabetization

Users will list the files with ls countless times. Help them see the relationships between the files by naming them so that related files appear together when listed in alphabetical order. Begin the file name with the most important word (like setup or hold), followed by the next important (like operating conditions) and so on.

Use leading zeros for numerical values so that alphabetical order is also numerical order, like the temperature values in,

setup.typ_1p2_000.rpt
setup.typ_1p2_025.rpt
setup.typ_1p2_100.rpt

Use Standard File Extension Names

Always use the standard file extension names for,

• Source code files, so that your text editor can do proper syntax highlighting. For example, .cpp, .py, .tcl, .v.
• Industry standard formats: .def, .lef, .lib, .sdc, .spef and so on
• Graphics files, so that they are correctly displayed: .jpg, .png, .gif.
• Files that you expect Microsoft Windows to recognize: .txt, .csv. Don’t forget to do unix2dos before trying to read Linux files with Windows.

Many files have no official file extension. Still, your flow will be much easier to understand if you use the most recognizable one:

• Log files use .log
• Report files use .rpt (although I do see a lot of Synopsys PrimeTime reports with .pt)
• For binary data with no other customary name, use something like .dat. Reserve .db for Synopsys database files.
• GDSII stream files use .gds (best), .gdsii or .gds2
• It is common to use a variety of file extensions for Verilog such as .v for RTL, and .vg for gate level, At least start with .v.

Whatever file extensions you choose, be consistent and use the same ones throughout your flow.

Use Directories Sparingly

You already have a tool working directory within a design directory. There is not much to be gained by partitioning your files into even more sub-directories. It often only serves to hide files and increase the amount of typing required. Certainly there is no need for any more than one level of sub-directory below the tool working directory.

Instead of distinguishing a file using a directory, consider simply lengthening the file name. For example, use setup.typ_1p2_100.rpt instead of setup/typ_1p2_100.rpt.

When you create a sub-directory within the tool working directory, use a short name. Reuse the same name wherever possible.

Still, some kinds of sub-directories make sense:

• A physical verification tool working directory is a special case. It generally contains separate working directories for LVS and DRC. For example, Mentor Calibre LVS is generally run in working directory designName/calibre/lvs, and DRC is run in designName/calibre/drc.
• A directory that contains input data, or data that retained for use in subsequent iterations of the design flow. Pin placement files and floorplan files are examples of this. Keeping input files in a separate directory sets them apart and protects them from accidental deletion.
• Many flow designers like to add directories like log/ and rpt/. Myself, I get along fine without either one. Directories like these are a matter of taste.

I have seen a few kinds of sub-directories that should be avoided:

• A sub-directory for databases that are organized as libraries, like Milkyway, CDB and OpenAccess. Such a sub-directory usually ends up containing just a single library, so it is completely redundant. Put libraries in the working directory.
• Sub-directories that attempt to artificially partition the design process for a tool into phases like design/ and analysis/. As your flow evolves, the boundary between the phases will drift, and you will end up storing almost everything in, say, design/, with a just a few orphan files left in analysis/.

Avoid Hidden Files

Hidden files (UNIX files that start with “.”) are a mean trick. Avoid them. Still, the initialization file for some design tools is a hidden file, like .cdsinit, .avantrc or .synopsys_pt.setup. Changing the initialization file name is an even meaner trick, so use the standard initialization file name regardless of whether it is hidden.

Name the Library Path the Same as the Library Name

OpenAccess and Cadence Virtuoso CDB allow you to specify a library path that is unrelated to the library name. For example, you might use the lib.defs or cds.lib file to specify that the library named blockHead is in directory /path/to/BH2.7. Without the lib.defs or cds.lib file, there is no way to know the name of the library in /path/to/BH2.7. This path should be rearranged so that it ends with the library name, for example /path/to/2.7/blockhead.

With Synopsys Milkyway, this is not an issue. The directory in which the library is stored is always the same as the library name. This is the right way to do it.

File Completion in Two Characters

Chris verBerg has a fun rule. He tries to name source files such that the first two characters are unique, so he need only type two characters, and file name completion will finish the name. Full file name completion might be too much to ask for design data files, but it is an excellent goal for sections of file names. For example, you could quickly find setup.typ_1p2_100.rpt
by typing “se” <Tab> “ty” <Tab>, and so on.

In particular, do not use names with similar prefixes, like place.log and placement.rpt. Choose either “place” or “placement”.