This tutorial will introduce you to the use of the Concurrent Versions System (CVS) to help manage design revisions in group projects that use Cadence design databases. Find a partner who can work on this tutorial with you and find a place where you can work side-by-side.

Person 1: Create the “horz” cell

First, one person should create a new directory to work in, called something like “cvstut”. Change to this directory, start icfb and create a library called “mylib” and a new layout cell-view called “horz”. As illustrated below, add a box in the “prBoundary” “drawing” layer and a horizontal “metal1” wire that spans the upper half of the box.

Save this design and exit icfb. Next, edit your cds.lib file. The library paths in this file point to the absolute locations for these libraries, but we want relative paths so that your partners will be opening their own private versions of the library. Do that by editing your file to look like the following:

INCLUDE ~/cds.lib
DEFINE mylib ./mylib

This is assuming that you have a cds.lib file in your home directory that defines all of the technology libraries.

Either Person: Create the Repository

Next, one person should create a directory for your repository. This directory will contain all versions of your design, so it’s best to put it somewhere that you’re very unlikely to delete or modify by mistake. I would suggest putting it in a directory at the root of your workspace, in a directory called “REPOSITORY”. Make sure that both of you have read and write access to this directory (rlidwkpermissions in AFS). See the AFS Permissions Page for help on setting permissions on your directories. If you create the repository in your group workspace, then the permissions should already be set for you.

Next set the CVSROOT environment variable with the command

setenv CVSROOT [repository path]

The repository path should be an absolute path. It’s helpful to add this command to your .mycshrc file so that you don’t have to type it in every time you log in.

Next, make sure that CVS is in your path. If you are running on Linux, it should be in your path automatically, but on Solaris machines, you will have to add it with the command

add rcstools

Finally, initialize the repository with the command

cvs init

This command needs only be executed once!

Person 1: Import the “horz” design

Now we will import the entire “cvstut” directory to your repository. Before doing this, it is helpful to clean up the files that don’t need to be in the repository (like “libManager.log” and so forth). Be sure to leave the cds.lib file and mylib directory intact. Make sure that you have exited icfb, or else you may still have some .cdslck files in your library directory (this would be bad, because the lock files will appear in your partner’s directory as well).

Change to the “cvstut” directory, and enter the command

cvs import -kb -m "Initial Revision" cvstut ncsu cvstut_0

This command imports the entire tree into the repository directory cvstut. The -kb option is needed because some of the files are binary, and the -m option gives a log message for this operation. The last two options give branch and revision tags, which are not very important for now but cannot be omitted. See the Using CVS page for more information about the cvs import command.

After executing this command, you should see files appear in your repository that correspond to the files you imported, each with a “,v” extension. DO NOT MODIFY THESE FILES! They contain all of the information necessary to re-create any version of your design.

Person 1: Create the Private Source Directory

Now that the design has been checked into the repository, it’s good practice to do all of your work in a private source directory, so that changes can be easily checked in to the repository. To do this, first delete your cvstut directory with the command

rm -rf cvstut

Note that if you have rm aliased to rm -i (as many people do), then you can avoid having to confirm every file deletion by using \rm instead of simply rm.

Next, check out your design again with the command

cvs co cvstut

You should see the directory re-created, this time with a sub-directory called “CVS” in every directory. This sub-directory contains the information necessary to identify how each file in this private source directory relates to the repository.

Now you should be able to re-start icfb and open the horz cell again.

Person 2: Create the “vert” cell

Now, the second person should login, set the CVSROOT environment variable, and add CVS to the path, and execute the command “cvs co cvstut” as described above. You will notice that you may open the “horz” cell-view for editing, if you wish. CVS does not restrict the number of people who may edit a file. However, if two people edit the same file, then you may create conflicts (see Resolving Conflicts on the Using CVS page for more information), so it’s best to agree ahead of time who “owns” each file.

Create a new layout cell-view called “vert”, and create an instance of the “horz” cell inside this cell. Next, create a vertical “metal2” wire with a “M2_M1” contact over the “metal1” wire as shown below.

Next, we’ll add this cell-view to the repository. Save the cell and exit icfb. You could use the “cvs add -kb” command on every new directory and file, followed by “cvs ci”, but this takes a lot of time. You can do this much more quickly by changing to the “cvstut/mylib/vert” directory and entering the command

cvs import -kb -m "Initial Revision" cvstut/mylib/vert ncsu cvstut_0

This will import the new cell into the repository at the location cvstut/mylib/vert.

Next, the second person should remove the “cvstut/mylib/vert” directory with the “rm -rf” command, and BOTH of you should change to the directory above the “cvstut” directory” and enter the following command:

cvs co cvstut/mylib/vert

This will add the new cell to your private source directories.

Person 1: Modify the “horz” cell

Next, the first person should open the “horz” cell and move the “metal1” shape down, as shown below.

Save the design (no need to exit icfb this time). Check your changes in by entering the following command from the “cvstut” directory:

cvs ci -m "Moved metal1"

The -m option allows you to specify a message about what you changed. If you omit the -m option, then CVS will open up a text editor, forcing you to enter a message. It’s easiest to simply use the -moption.

Person 2: Update the “horz” cell

Next, the second person should enter the following command from the “cvstut” directory:

cvs update >& update.log

The cvs update command will copy the latest versions of each file in your private souce directory from the repository. Examine the update.log file to see progress of the command as it examined each directory. The letter “U” will appear at the beginning of a line to indicate that a file was updated. Save this file to turn in.

Person 2: Modify the “vert” cell

Next, the second person should open the “vert” cell. Notice that the M2_M1 contact is no longer aligned, as shown below.

Move the M2_M1 contact so that it is aligned, as shown below:

Save the cell-view, change to the “cvstut” directory and enter the following command:

cvs ci -m "Moved contact"

You should see messages as CVS reports that it finds modified files and checks them in.

Person 1: Update the “vert” cell

Finally, the first person should enter the following command from the “cvstut” directory:

cvs update >& update.log

As before, the cvs update command will copy the latest versions of each file in your private souce directory from the repository. Examine the update.log file to see progress of the command as it examined each directory. You should notice a “U” by each file in the “vert” cell. Open this cell to view the modified contents, and save the update.log file to turn in.

For more information

For more information about the CVS command, read through the Using CVS page. Commercial versioning databases for integrated circuit design are more advanced than CVS, but all of them work on the same principles. Mastering CVS in your design projects will not only save you time and effort, but will also help a great deal to prepare you for work on large commercial chip designs.