# $Id: //guest/robert_yu/perforce/icp4-1.1/doc/Icp4.txt#2 $
# Copyright (C) 2008 Robert K. Yu
# email: [email protected]
# This file is part of Icp4.
# Icp4 is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2, or (at your option)
# any later version.
# Icp4 is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with Icp4; see the file COPYING. If not, write to the
# Free Software Foundation, Inc., 59 Temple Place - Suite 330,
# Boston, MA 02111-1307, USA.
1. Mentor Directory Structure
--------------------------
By inspection, Mentor's icstudio keeps files in a directory structure
organized by:
<project>/<lib>/<group>/<view>/<cell>
where
<project> := <name>.proj
<lib> := <name>.lib
<group> := <name>.group (note: "default.group")
<view> := [layout|logic].views
Files under the <cell> directories are organized differently depending
whether its a schematic (mentor calls this "logic") or layout.
There are various ".attr" files that contain information about
the latest versions (last 4 for layouts and last 2 for schematics
are kept.) These ".attr" files also keep track of which version of
cells are instantiated. The actual data is kept in various binary
files with filetypes like
.part_N
.ssht_N
.sgfx_N
.iccel_N
etc
where N is Mentor's revision number. The .attr file seems to also
contain unexpected information like hostid, macid, dates, etc. which
make it difficult to hack around. It would be desirable to turn off
their database management system altogether and have them keep only
one version and always write to that same file, but in any event,
I have opted to take a simple approach: Namely, treat everything
underneath <cell> directories as a group for the purpose of database
management and version control with Perforce.
2. Icp4: Perforce Integration with Mentor
--------------------------------------
Icp4 is a set of perl scripts written to integrate Perforce with
Mentor's icstudio files. (The two main advantages to Perforce are
speed and flexibility. See www.perforce.com for details.)
All Icp4 operations are done at the command line at the <view>
directory level. Icp4 knows about certain filetypes (defined in
lib/Icp4.pm) :
@icstudio_patterns = (
'\.part_\d+$', # schematic
'\.ssht_\d+$', # schematic
'\.sgfx_\d+$', # schematic
'\/schem_id$', # schematic
'\.smbl_\d+$', # symbol
'\.iccel_\d+$', # layouts
'\.attr$',
);
The Icp4 typemap is defined as:
binary+l //.../*.part_*
binary+l //.../*.smbl_*
binary+l //.../*.ssht_*
binary+l //.../*.sgfx_*
binary+l //.../*.iccel_*
binary+l //.../schem_id
binary+l //.../*.fz_*
text+l //.../*.attr
This means that only the matching files found anywhere below the
<cell> directory will be checked in. These files are treated as binary
files, and are "locked" whenever they are checked out. (Perforce
supports both the "lock-modify-unlock" and the "copy-modify-merge"
models, but for ic design, the lock approach is preferred.)
A. Checking in a cell
To check in any updates/new cell:
% cd <view>
% p4ci <cell>+
OR
From $MGC_WD:
% p4local -a <dir>
% p4 revert -a <dir>... // optional
% p4 submit <dir>...
OR
% cd <dir>
% p4local -a .
% p4 revert -a ... // optional
% p4 submit ...
where:
<view>:= <project>/<lib>/<group>/<view>
<dir> := .
<project>
<project>/<lib>
<project>/<lib>/<group>
<project>/<lib>/<group>
<project>/<lib>/<group>/<view>
To checkin data, Icp4 looks for any new files found underneath the
<cell> directory. Because of icstudio's versioning mechanism,
new files are created for every new version of that cell.
These newly created files are added into the perforce database.
A revert is then performed to unedit any unchanges files.
This operation was added to avoid checking in files that have
unchanged content. The last step is to submit the addition and
changes to the perforce database. This submit operation treats
all files underneath a given cell as a group, and assigns a
"changelist" number with the operation. This "changelist"
number is saved in the database, and appears in the revision
history of any file in the set. This "changelist" number is
used later on to revert back to any saved state of that cell.
Note that perforce will save every version that it finds
underneath the <cell> directory, even though icstudio is only
aware of only the last 4 layout and the last 2 schematic.
If icstudio disables their versioning mechanism, then this
"finding and adding" of new files is not needed, resulting in
faster checkins and smaller databases. In the future, I plan
on adding a feature in Icp4 to "delete" old versions of files.
(With the perforce delete command, a file is not really removed
from the database. It just does not show up when a user sync's
up to it.)
Note that the p4ci command takes on one or many cells. All cell
changes will then be submitted at the same time under one
"changelist". This is useful for keeping sets of compatible
cell together.
p4ci exits with error if it comes across a "lck" file. This
means it is currently open for edit, and the latest version
may not be saved on disk.
B. Checking out a cell
To check out a cell:
% cd <view>
% p4co <cell>+
OR
From $MGC_WD:
% p4 edit <dir>...
OR
% cd <dir>
% p4 edit ...
This does nothing special above the normal "p4 edit" command.
The "p4co" command was provided to allow users to operate perforce
on cells.
C. Updating your database
To update a client's workspace:
% cd <view>
% p4 sync [-f] <cell>
OR
% p4 sync [-f] ...
D. Unedit unchanged cells (leave any changed cells alone):
To unedit an unchanged cell:
% cd <view>
% p4 revert -a <cell>...
OR
From $MGC_WD:
% p4 revert -a <dir>...
E. Unedit changed cells:
To unedit an changed cell, discarding any changes made:
% cd <view>
% p4 revert <cell>...
OR
From $MGC_WD:
% p4 revert <dir>...
F. See what's checked out:
% cd <dir>
% p4 opened [-a] ...
OR
From $MGC_WD:
% p4 opened [-a] <dir>...
G. See the history of a cell:
For schematics:
% cd <view>
% p4 filelog [-l] <cell>/schematic.mgc_schematic.attr
For layouts:
% cd <view>
% p4 filelog [-l] <cell>/<cell>.Ic_cell_template.attr
(I may write a script to hide these details.)
H. Restoring to an older version:
To restore an older version of a cell, first show
the history, then sync to the correct "changelist"
number. For example:
% p4 filelog -l test1/schematic.mgc_schematic.attr
... #6 change 14 edit on 2004/10/23 by ryu@ryu_p4 (text+l)
fixed power bug
... #5 change 13 edit on 2004/10/23 by ryu@ryu_p4 (text+l)
optimized for power
... #4 change 12 edit on 2004/10/23 by ryu@ryu_p4 (text+l)
yet another bug
... #3 change 7 edit on 2004/10/20 by ryu@ryu_p4 (text+l)
corrected bug
... #2 change 6 edit on 2004/10/20 by ryu@ryu_p4 (text+l)
optimized for timing
... #1 change 5 add on 2004/10/20 by ryu@ryu_p4 (text+l)
initial design
To restore back to "change 12", simply:
% p4 sync @12