cell.java

The ElectricTM VLSI Design System is an open-source Electronic Design Automation (EDA) system that c

/* -*- tab-width: 4 -*-
 *
 * Electric(tm) VLSI Design System
 *
 * File: Cell.java
 *
 * Copyright (c) 2003 Sun Microsystems and Static Free Software
 *
 * Electric(tm) 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 3 of the License, or
 * (at your option) any later version.
 *
 * Electric(tm) 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 Electric(tm); see the file COPYING.  If not, write to
 * the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
 * Boston, Mass 02111-1307, USA.
 */
package com.sun.electric.database.hierarchy;

import com.sun.electric.database.CellBackup;
import com.sun.electric.database.CellRevision;
import com.sun.electric.database.EObjectInputStream;
import com.sun.electric.database.EObjectOutputStream;
import com.sun.electric.database.IdMapper;
import com.sun.electric.database.ImmutableArcInst;
import com.sun.electric.database.ImmutableCell;
import com.sun.electric.database.ImmutableExport;
import com.sun.electric.database.ImmutableNodeInst;
import com.sun.electric.database.Snapshot;
import com.sun.electric.database.constraint.Constraints;
import com.sun.electric.database.geometry.DBMath;
import com.sun.electric.database.geometry.ERectangle;
import com.sun.electric.database.geometry.Poly;
import com.sun.electric.database.id.CellId;
import com.sun.electric.database.id.CellUsage;
import com.sun.electric.database.id.PortProtoId;
import com.sun.electric.database.id.TechId;
import com.sun.electric.database.network.Netlist;
import com.sun.electric.database.network.NetworkTool;
import com.sun.electric.database.prototype.NodeProto;
import com.sun.electric.database.prototype.PortProto;
import com.sun.electric.database.text.ArrayIterator;
import com.sun.electric.database.text.CellName;
import com.sun.electric.database.text.ImmutableArrayList;
import com.sun.electric.database.text.Name;
import com.sun.electric.database.text.TextUtils;
import com.sun.electric.database.topology.ArcInst;
import com.sun.electric.database.topology.Geometric;
import com.sun.electric.database.topology.NodeInst;
import com.sun.electric.database.topology.PortInst;
import com.sun.electric.database.topology.RTBounds;
import com.sun.electric.database.topology.Topology;
import com.sun.electric.database.variable.EditWindow0;
import com.sun.electric.database.variable.ElectricObject;
import com.sun.electric.database.variable.TextDescriptor;
import com.sun.electric.database.variable.Variable;
import com.sun.electric.technology.AbstractShapeBuilder;
import com.sun.electric.technology.ArcProto;
import com.sun.electric.technology.PrimitiveNode;
import com.sun.electric.technology.SizeOffset;
import com.sun.electric.technology.TechPool;
import com.sun.electric.technology.Technology;
import com.sun.electric.technology.technologies.Generic;
import com.sun.electric.technology.technologies.Schematics;
import com.sun.electric.tool.Job;
import com.sun.electric.tool.ncc.basic.NccCellAnnotations;
import com.sun.electric.tool.user.ActivityLogger;
import com.sun.electric.tool.user.CircuitChangeJobs;
import com.sun.electric.tool.user.ErrorLogger;
import com.sun.electric.tool.user.User;

import java.awt.Dimension;
import java.awt.geom.AffineTransform;
import java.awt.geom.Point2D;
import java.awt.geom.Rectangle2D;
import java.io.IOException;
import java.io.InvalidObjectException;
import java.io.NotSerializableException;
import java.util.ArrayList;
import java.util.BitSet;
import java.util.Collections;
import java.util.Date;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.NoSuchElementException;
import java.util.Set;
import java.util.TreeSet;
import java.util.prefs.BackingStoreException;
import java.util.prefs.Preferences;

/**
 * A Cell is a non-primitive NodeProto.
 * Besides the information that it inherits from NodeProto, the Cell holds a
 * set of nodes, arcs, and networks.
 * The exported ports on NodeInsts inside of this cell become the Exports
 * of this Cell.
 * A Cell also has a specific view and version number.
 * <P>
 * It is possible to get all of the versions of the cell.
 * A Cell knows about the most recent version of itself, which may be itself.
 * <P>
 * Cells also belong to CellGroup objects, which gather related cells together.
 * <P>
 * <CENTER><IMG SRC="doc-files/Cell-2.gif"></CENTER>
 * <P>
 * A Cell can have different views and versions, each of which is a cell.
 * The library shown here has two cells (?gate? and ?twogate?), each of which has many
 * views (layout, schematics, icon, vhdl) and versions:
 * <P>
 * <CENTER><IMG SRC="doc-files/Cell-1.gif"></CENTER>
 */
public class Cell extends ElectricObject implements NodeProto, Comparable<Cell>
{
	// ------------------------- private classes -----------------------------

	/**
	 * A CellGroup contains a list of cells that are related.
	 * This includes different Views of a cell (e.g. the schematic, layout, and icon Views),
	 * alternative icons, all the parts of a multi-part icon.
	 */
	public static class CellGroup
	{
		// private data
        private final Library lib;
		private TreeSet<Cell> cells;
		private Cell mainSchematic;
		private CellName groupName;

		// ------------------------- public methods -----------------------------

		/**
		 * Constructs a CellGroup.
		 */
		private CellGroup(Library lib)
		{
            this.lib = lib;
            cells = new TreeSet<Cell>();
		}

        /**
         * Constructor for Undo.
         */
        CellGroup(TreeSet<Cell> cells) {
            lib = cells.first().getLibrary();
            this.cells = cells;
            setMainSchematics(true);
            for (Cell cell: cells) {
                assert cell.getLibrary() == lib;
                cell.cellGroup = this;
            }
        }

		/**
		 * Method to add a Cell to this CellGroup.
		 * @param cell the cell to add to this CellGroup.
		 */
		private void add(Cell cell)
		{
            lib.checkChanging();
            Cell paramOwner = getParameterOwner();
			synchronized(cells)
			{
                if (!cells.contains(cell))
				    cells.add(cell);
                setMainSchematics(false);
			}
			cell.cellGroup = this;
            if (cell.getD().paramsAllowed() && paramOwner != null)
                cell.setParams(paramOwner);
		}

		/**
		 * Method to remove a Cell from this CellGroup.
		 * @param f the cell to remove from this CellGroup.
		 */
		private void remove(Cell f)
		{
            lib.checkChanging();
			synchronized (cells)
			{
				cells.remove(f);
                setMainSchematics(false);
			}
            f.cellGroup = null;
		}

		/**
		 * Method to return an Iterator over all the Cells that are in this CellGroup.
		 * @return an Iterator over all the Cells that are in this CellGroup.
		 */
		public Iterator<Cell> getCells() { return cells.iterator(); }

		/**
		 * Method to return the number of Cells that are in this CellGroup.
		 * @return the number of Cells that are in this CellGroup.
		 */
		public int getNumCells() { return cells.size(); }

		/**
		 * Method to return a List of all cells in this Group, sorted by View.
		 * @return a List of all cells in this Group, sorted by View.
		 */
		public List<Cell> getCellsSortedByView()
		{
			synchronized(cells)
			{
				List<Cell> sortedList = new ArrayList<Cell>(cells);
				Collections.sort(sortedList, new TextUtils.CellsByView());
				return sortedList;
			}
		}

		/**
		 * Method to return main schematics Cell in this CellGroup.
		 * The main schematic is the one that is shown when descending into an icon.
		 * Other schematic views may exist in the group, but they are "alternates".
		 * @return main schematics Cell in this CellGroup.
		 */
		public Cell getMainSchematics()
		{
			return mainSchematic;
		}

		/**
		 * Method to return parameter owner Cell in this CellGroup.
		 * The param owner Cell is icon or schematic Cell whose parameters
         * are used as reference when reconcilating parameters of other icon/schematic
         * Cells in the group.
		 * Param owner Cell is either main schematic Cell or first icon in alphanumeric
         * order in CellGroups without schematic Cells
		 * @return parameter owner Cell in this CellGroup.
		 */
		public Cell getParameterOwner() {
            if (mainSchematic != null)
                return mainSchematic;
            for (Cell cell: cells) {
                if (cell.isIcon())
                    return cell;
            }
            return null;
		}

        /**
         * Method to add a parameter on icons/schematics of this CellGroup.
         * It may add repaired copy of this Variable in some cases.
         * @param param parameter to add.
         */
        public void addParam(Variable param) {
            for (Cell cell: cells) {
                if (!(cell.isIcon() || cell.isSchematic())) continue;

            	// find nonconflicting location of this cell attribute
            	Point2D offset = cell.newVarOffset();
                cell.addParam(param.withOff(offset.getX(), offset.getY()));
            }
        }

        /**
         * Method to delete a parameter from icons/scheamtics this CellGroup.
         * @param key the key of the parameter to delete.
         */
        public void delParam(Variable.AttrKey key) {
            for (Cell cell: cells) {
                if (!(cell.isIcon() || cell.isSchematic())) continue;
                cell.delParam(key);
            }
        }

        /**
         * Rename a parameter. Note that this creates a new variable of
         * the new name and copies all values from the old variable, and
         * then deletes the old variable.
         * @param key the name key of the parameter to rename
         * @param newName the new name of the parameter
         */
        public void renameParam(Variable.AttrKey key, Variable.AttrKey newName) {
            if (newName == key) return;
            for (Cell cell: cells) {
                if (!(cell.isIcon() || cell.isSchematic())) continue;
                cell.renameParam(key, newName);
            }
        }

        /**
         * Method to update a parameter on icons/schematics of this CellGroup with the specified values.
         * If the parameter already exists, only the value is changed; the displayable attributes are preserved.
         * @param key the key of the parameter.
         * @param value the object to store in the parameter.
         */
        public void updateParam(Variable.AttrKey key, Object value) {
            assert cells.iterator().next().isParam(key);
            for (Cell cell: cells) {
                if (!(cell.isIcon() || cell.isSchematic())) continue;
        		Variable oldParam = cell.getParameter(key);
                cell.addParam(oldParam.withObject(value));
            }
        }

        /**
         * Method to update a text parameter on icons/schematics of this ElectricObject with the specified values.
         * If the Parameter already exists, only the value is changed;
         * the displayable attributes and Code are preserved.
         * @param key the key of the parameter.
         * @param text the text to store in the patameter.
         */
        public void updateParamText(Variable.AttrKey key, String text) {
            assert cells.iterator().next().isParam(key);
            for (Cell cell: cells) {
                if (!(cell.isIcon() || cell.isSchematic())) continue;
        		Variable oldParam = cell.getParameter(key);
                cell.addParam(oldParam.withText(text));
            }
        }

        /**
         * Method to tell whether this CellGroup contains a specified Cell.
         * @param cell the Cell in question.
         * @return true if the Cell is in this CellGroup.
         */
        public boolean containsCell(Cell cell) { return cell != null && cells.contains(cell); }

		/**
		 * Returns a printable version of this CellGroup.
		 * @return a printable version of this CellGroup.
		 */
		public String toString() { return "CellGroup " + getName(); }

		/**
		 * Method to compare two CellGroups.
		 * Because CellGroups seem to be ephemeral, and are created dynamically,
		 * it is not possible to compare them by equating the object.
		 * Therefore, this override compares the group names.
		 * Although not accurate, it is better than simple object equality.
		 */
		public boolean equals(Object obj)