Give Files in Your IC Design Flow Meaningful Names

When a user wants chip design data, a script or a log file, how do they find it? They look at the file and directory names. In fact, this may be the only documentation available.

As an IC design flow architect, proper file naming is the most important thing you can do to guide your users to the data they need.  Further, you need to use safe names that can be used without transformation for any purpose, on any computing platform.

This is one of a series of articles on simple, specific techniques that will make your chip design flow easy to use. Other articles include,

What You Should See in Every File Name

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

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 JIRA or 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.

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 design directories into a hierarchy of directories that match the chip hierarchy. Put the design directories wherever they make sense in your work flow.

Within the design directory, there is little need to further repeat the design name in file names.  The design name need only be used in the names of files that will be used together with files from other designs:

  • 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

Overusing the design name just makes it harder for users and scripts to remember the correct file name. For example, Cadence SoC Encounter floorplan files are used only within a single design, so skip the design name and give them names like floorplan.fp.

Many times a tool will have a default name for a file.  Use that name whenever you can.

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.

Each tool should write files only to its own directory.  This way, if a file appears in directory cdesigner/, all users understand that Synopsys Custom Designer wrote that file.  If a file created by Cadence Virtuoso is needed, everyone knows that it can be found in ../virtuoso/.

I have seen flows organized with the tool directory above and the design directory within, like 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.

Do note that this rule refers only to literal paths that remain static between runs of the flow, such as paths specified in a configuration file.  This rule does not apply to the contents of variables as the flow runs. It is in fact quite common, and even beneficial for variables to contain absolute paths.  The key here is that absolute paths should be built dynamically, so that each time the user runs your flow, absolute paths are recalculated to match the location of the run directory.

Even literal absolute path names have their place. It is reasonable to use a fully qualified path to things that are do not move along with 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.

Symbolic links are not supported by Windows, so if you use them you will not be able to port your flow to Windows, or even copy your data to a Windows file system.

Use Names Compatible with Verilog

Steps, variables, files, directories, scripts and designs should share the same name whenever it makes sense.  Yet when you invent a new name for something, it is difficult to know where else you might need to use it.

The most restrictive name space used in IC design is Verilog, so obey Verilog naming rules when choosing any name. This way, whenever you decide that step, design file or directory names should match, they can match without complicated escape sequences.

The Verilog naming rules are so simple and natural that most names you might make up would be legal anyway:

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

Within file names, use ‘.‘ (period) as a delimiter between sections of file names. Use as many as you need. Do not use ‘_‘. For example, suppose you named your floorplan DEF files,

designName_floorplan.def       # Bad form

where designName is the name of the design.  This is a problem because xyz_floorplan is a legal Verilog design (module) name. Nobody can be sure whether _floorplan is part of your file naming convention.  On the other hand, if you use ‘.‘ as the delimiter,

designName.floorplan.def       # Good form

the file name can be parsed because xyz.floorplan is not a legal Verilog module name.

Preserve your platform independence by avoiding any other characters.  For example, the Milkyway design blockHead.CEL;3 is stored on disk in file CEL/blockHead:3.  Since Windows does not allow ‘:‘ in file names, this file cannot be copied to a Windows file system.

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 is 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 standard initialization file for some design tools is a hidden file, such as .cdsinit or .synopsys_pt.setup. Changing the initialization file name is an even meaner trick, so always 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 verBurg 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, never use slightly different names that mean the same thing, like place.log and placement.rpt. Choose either “place” or “placement”.  Actually “place” should be used because it is a verb.