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,
- 1 What You Should See in Every File Name
- 2 Choose a Step Name and Use It for Everything
- 3 One Design Per Directory
- 4 A Working Directory for Each Tool
- 5 Use Relative Paths, Avoid Symbolic Links
- 6 Use Names Compatible with Verilog
- 7 Name for Alphabetization
- 8 Use Standard File Extension Names
- 9 Use Directories Sparingly
- 10 Avoid Hidden Files
- 11 Name the Library Path the Same as the Library Name
- 12 File Completion in Two Characters
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 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:
- 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,
placeMax.rpt. This way, all files related to step
place appear together when listed alphabetically.
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
blockHeadshould be saved to OpenAccess as
blockHead/blockHead/layout, or in Milkyway as
- GDSII file, like
- Text format files, like
- Design name in the database. Use the most ordinary view name. For example, the completed layout for design
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
Many times a tool will have a default name for a file. Use that name whenever you can.
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
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
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
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.
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
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.
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
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,
Always use the standard file extension names for,
- Source code files, so that your text editor can do proper syntax highlighting. For example,
- Industry standard formats:
.spefand so on
- Graphics files, so that they are correctly displayed:
- Files that you expect Microsoft Windows to recognize:
.csv. Don’t forget to do
unix2dosbefore 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
- Report files use
.rpt(although I do see a lot of Synopsys PrimeTime reports with
- For binary data with no other customary name, use something like
.dbfor Synopsys database files.
- GDSII stream files use
- It is common to use a variety of file extensions for Verilog such as
.vfor RTL, and
.vgfor gate level, At least start with
Whatever file extensions you choose, be consistent and use the same ones throughout your flow.
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
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
- 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
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
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
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
.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.
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
cds.lib file to specify that the library named
blockHead is in directory
/path/to/BH2.7. Without the
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
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.
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
by typing “
se” <Tab> “
ty” <Tab>, and so on.
In particular, never use slightly different names that mean the same thing, like
placement.rpt. Choose either “place” or “placement”. Actually “place” should be used because it is a verb.