#	$Id: //guest/robert_yu/perforce/icp4-1.1/doc/Icp4.txt#2 $

#	Copyright (C) 2008 Robert K. Yu
#	email: ryu@cswitch.com

#	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