CDSP4 HowTo
 
Shiv Sikand <sikand@users.sourceforge.net>
 
What is cdsp4 ?
 
Cdsp4 is a high performance, (mostly) OpenSource integration of
Cadence DFII and Perforce. (www.perforce.com).
 
Mostly ?
 
The integration consists of two parts...a pair of GDM ( Generic Design
Management) executables, p4fisrv and p4gdmconfig (Solaris only at the
present time) and a bunch of Skill. The GDM stuff is proprietary since
it links with Cadence's GDM api. However, the nature of the cdsp4
integration means that all the work is performed in Skill, so no edits
are needed to p4fisrv, which is a specially crafted server.
 
Copyright and Legal Notice (p4fisrv and p4gdmconfig)
 
You may not use p4firsrv for any other purpose other than to
facilitate the cdsp4 integration. You are bound by the same terms and
conditions of the Cadence end user license agreement.
 
Copyright and Legal Notice (Skill code)
 
This code is provided under the BSD source license. The copyright
holder is Perforce Software.
 
OK, now that's out of the way, let's move on.
 
Who wrote it ?
 
Cdsp4 was written at SGI between 1998and 2000 by Shiv Sikand and Dan
Freitas. It has been succesfully deployed for a number of different
chips. SGI open sourced it in line with their commitment to the open
source community.
 
 
How is it supported ?
 
The integration is community supported at the present time. Should it
become widespread, Perforce Software will support it. Perforce itself,
is of course, fully supported.  Perforce is a member of the Cadence
Connections program and will work to deliver working integrations for
all major Cadence releases. Cadence supports this work through the
membrship of Perforce in the Connections program.
 
 
What are it's limitations at the present time ?
 
Since Version 1 is a Skill integration and not a 'pure' GDM integration, it will not work with tools that do not use Skill. A classic example is StreamIn or VerilogIn. (nino/pipo binaries). However, simple scripts run in -nograph mode can cover this kind of functionality very easily.
 
Version 2, due in 2001, will support both Skill and non-Skill tools. However, the non-Skill support cannot be open sourced due to the GDM license agreement, so it likely to provide only very basic functionality to avoid secondary scripting.
 
What are it's advantages ?
 
It's very fast, has the richest feature set of any available DFII
integration, it's fairly bug free, you get the source and it's free.
 
What's the catch [1]?
 
You have to buy Perforce, but it is pretty cheap in
comparison. ($600/users with volume discounts. See the Perforce Web
Page for more details).
 
What's the catch [2]?
 
The secret to a good data management system is it's ability to do
Configuration Management, or CM. This is the ability to take your data
set backwards or forwards to any point in time with the greatest of
ease. In order to make this happen, you need to adopt the cdsp4 method
of branch and replace. For more details, read my paper, 'Advanced
OpenSource DM for Cadence 4.4, which is included as a pdf file in this
directory.
 
What's different in the UI ?
 
The biggest change is the library browser. You cannot use the default
browser and must use the listBoxBrowser library manager that is part
of the integration. It's your one stop shop for all DM
functions. Also, handle all your library and cell creation requests
through lbb. Don't use the file commands on the CIW for creating
managed libraries. It's ok to use them for un-managed libraries.
 
What do I need to know before I begin ?
 
Basics
 
Before you begin, you need to educate yourself on how 'p4' works. You
can download a limited user version for free from the Perforce Web
Site.
 
Atomic transactions
 
This is one of the key features and is used at two levels of
granularity. The first level handles the Cadence co-managed sets. A
co-managed set is a simply a set of files that make up a cellview or
other design object. All the other tools that I have seen use two or
more additional files per cellview to handle this feature, resulting
in very poor performance and potentially, reliability.
 
In cdsp4, the co-managed set is an atomic transaction. For this
reason, you should not checkin and checkout files using the p4 command
line interface unless you understand exactly what you are doing.  The
second level of granularity is used for reverse integration, which we
shall talk about in due course.
 
Branching and Integration
 
Once you are familiar with it's basic operation (add, edit, submit),
you need to familiarise yourself with the p4 InterFile Branching
mechanism. (p4 branch and p4 integrate). I suggest you check in some
files and play with these two commands and read the available
documentation. Once you figure this out, the rest is easy !!
 
 
The cdsp4 data flow model
 
From this point on, I'm assuming that you have a reasonable feel for
IFB. If, for any reason you think I am wrong, or the approach is
faulty, let me know. Without doubt, there are improvements that need
to be made to the data flow model, namely with multi level branches to
support multi-user sharing and communication (coming soon), but I
believe that the fundamentals are sound and have been extensively
reviewed by Software Configuration Management gurus. Your
contributions are welcome.
 
The basic premise of the model is that everyone works in a
branch. There is no direct editing of the mainline.
 
(BTW, most of the statements that I make with respect to the data flow
model are not mandatory, the code does not enforce many of these
conditions and in the instances where it does, the default behaviour
can be overriden using a global variable.)
 
The branches are under control of the user. Branches can be updated
from the mainline using the 'Integration Wizard' which automatically
tracks the dependencies of files and their parentage in your
branch. Changes in the branch are 'reverse integrated' back into the
mainline as an atomic transaction (on a per library basis) ensuring
consistency and reliability. An integration policy prohibits reverse
integration of data back into the mainline unless you are in-sync with
the mainline for files you have not edited.
 
 
The interface gives you the ability to move freely in revision space,
including deleted files, as many times as you like, without any
performance hit. Perforce has implict state control through its change
based architecture so you never need to 'tag'. Not that anything
prevents you from using tags or 'labels', as they are known in
Perforce speak.
 
This free movement applies to individual cells, entire libraries or
sets of libraries.
 
 
Installation specifics
 
Each library gets its own Perforce 'client'. In order to generate a
unique name, a scheme is used:
 
<libname>:<CDS_Project>_<CDS_Rev>
 
When a library is branched( using the buildbranch perl script), the syntax is
 
<libname>:<branchname> where the branchname takes the form
 
<CDS_Project>_<CDS_Rev>_<branchtype>_<3 character Month><Day>_<4 digitYear>
 
branchtype is a specifier such as 'block', 'top level', 'rtl' etc.
 
Clients are for a library a located by reading a file known as
'cds.p4clients'. This file always has a corresponding cds.lib file. It
containts the library name, the library path and the corresponding
client that maps to that path.
 
The system tries to define a 'master' cds.lib file. Ie the cds.lib
file for the mainline and by extension, a master cds.p4clients file.
 
When a branch is built, a new cds.lib and cds.p4clients is generated
by the buildbranch script. (in the site-specific perl directory which
you will need to tweak/fix/rewrite for your own use. I definitely need
help here to build a more generic solution).
 
The user 'sees' a branch by running branchprep.pl. This assumes the
following:
 
In the dir where the command is run, there exists a cds.lib file which
references the master cds.lib file.
 
Eg
 
~sikand/opus44/cds.lib contains (at minimum) and include entry for the
mainline.
 
INCLUDE /projects/n1/rev1.0/cadence_libs/cds.lib
 
Assuming we have built a branch for some subsection of n1/rev1.0, (or
even all of it):
 
eg n1_rev1.0_top_Jan1_2000
 
then it will create a new cds.lib file 
 
n1_rev1.0_top_Jan1_2000/cds.lib
 
It also creates a file 
 
n1_rev1.0_top_Jan1_2000/.branchrc which defines a shell environment
variable, PROJECT_BRANCH.
 
It is up to you to make sure that your startup script for DFII detects
the existence of this file and source it, or you can do it manually
since that is how the intrface detects you are running in a branch.
 
It will also copy and display.drf files and any other files that begin
with '.cds'.
 
The interface needs to know how to find the appropriate cds.p4clients
file. The location is hard coded (for now, until I fix it) in the
CDS_P4Triggers.il file.
 
So, once you have fixed the definitions for CDS_P4MasterClientFile
(for both the mainline and branches) and have defined CDS_Project and
CDS_Rev and have followd the other insallation instructions in the
README file, you are ready to rock.
 
Revisioning a library
 
Often, this is the first step unless you have used my synchronicity to
p4 converter.
 
The default client mapping is again hardcoded and on the todo
list. However, there is a Custom View field that allows you to
override it. If you are revisioning a lot of libraries it would make
sense to generate your own sets of defaults.
 
 
<Lots more to come, of course, in due course, or with your help>