nodeinst.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: NodeInst.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.topology;

import com.sun.electric.database.CellBackup;
import com.sun.electric.database.EObjectInputStream;
import com.sun.electric.database.EObjectOutputStream;
import com.sun.electric.database.ImmutableArcInst;
import com.sun.electric.database.ImmutableExport;
import com.sun.electric.database.ImmutableNodeInst;
import com.sun.electric.database.ImmutablePortInst;
import com.sun.electric.database.constraint.Constraints;
import com.sun.electric.database.geometry.DBMath;
import com.sun.electric.database.geometry.EPoint;
import com.sun.electric.database.geometry.ERectangle;
import com.sun.electric.database.geometry.GenMath;
import com.sun.electric.database.geometry.Orientation;
import com.sun.electric.database.geometry.Poly;
import com.sun.electric.database.hierarchy.Cell;
import com.sun.electric.database.hierarchy.EDatabase;
import com.sun.electric.database.hierarchy.Export;
import com.sun.electric.database.hierarchy.Nodable;
import com.sun.electric.database.id.CellId;
import com.sun.electric.database.id.PortProtoId;
import com.sun.electric.database.prototype.NodeProto;
import com.sun.electric.database.prototype.PortOriginal;
import com.sun.electric.database.prototype.PortProto;
import com.sun.electric.database.text.ArrayIterator;
import com.sun.electric.database.text.ImmutableArrayList;
import com.sun.electric.database.text.Name;
import com.sun.electric.database.variable.DisplayedText;
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.VarContext;
import com.sun.electric.database.variable.Variable;
import com.sun.electric.technology.ArcProto;
import com.sun.electric.technology.PrimitiveNode;
import com.sun.electric.technology.PrimitiveNodeSize;
import com.sun.electric.technology.PrimitivePort;
import com.sun.electric.technology.SizeOffset;
import com.sun.electric.technology.Technology;
import com.sun.electric.technology.TransistorSize;
import com.sun.electric.technology.technologies.Artwork;
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.CircuitChangeJobs;
import com.sun.electric.tool.user.ErrorLogger;

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.Collections;
import java.util.HashSet;
import java.util.Iterator;
import java.util.List;
import java.util.NoSuchElementException;
import java.util.Set;

/**
 * A NodeInst is an instance of a NodeProto (a PrimitiveNode or a Cell).
 * A NodeInst points to its prototype and the Cell in which it has been
 * instantiated.  It also has a name, and contains a list of Connections
 * and Exports.
 * <P>
 * The rotation and transposition of a NodeInst can be confusing, so it is illustrated here.
 * Nodes are transposed when one of their scale factors is negative.
 * <P>
 * <CENTER><IMG SRC="doc-files/NodeInst-1.gif"></CENTER>
 */
public class NodeInst extends Geometric implements Nodable, Comparable<NodeInst>
{
	/** key of text descriptor with prototype name. */          public static final Variable.Key NODE_PROTO = Variable.newKey("NODE_proto");
	/** key of obsolete Variable holding instance name. */		public static final Variable.Key NODE_NAME = Variable.newKey("NODE_name");
	/** key of Varible holding outline information. */			public static final Variable.Key TRACE = Variable.newKey("trace");
	/** key of Varible holding serpentine transistor length. */	public static final Variable.Key TRANSISTOR_LENGTH_KEY = Variable.newKey("transistor_width");

	private static final PortInst[] NULL_PORT_INST_ARRAY = new PortInst[0];
//	private static final Export[] NULL_EXPORT_ARRAY = new Export[0];

    /**
	 * Method to detect if np is not relevant for some tool calculation and therefore
	 * could be skip. E.g. cellCenter, drcNodes, essential bounds and pins in DRC.
	 * Similar for layer generation
	 * @param ni the NodeInst in question.
	 * @return true if it is a special node (cell center, etc.)
	 */
	public static boolean isSpecialNode(NodeInst ni)
	{
		NodeProto np = ni.getProto();
		return (Generic.isSpecialGenericNode(ni) || np.getFunction() == PrimitiveNode.Function.PIN ||
		        np.getFunction() == PrimitiveNode.Function.CONNECT);
	}

	/**
	 * the PortAssociation class is used when replacing nodes.
	 */
	private static class PortAssociation
	{
		/** the original PortInst being associated. */			PortInst portInst;
		/** the Poly that describes the original PortInst. */	Poly poly;
		/** the center point in the original PortInst. */		Point2D pos;
		/** the associated PortInst on the new NodeInst. */		PortInst assn;
	}

	// ---------------------- private data ----------------------------------
    /** persistent data of this NodeInst. */                private ImmutableNodeInst d;
	/** prototype of this NodeInst. */						private final NodeProto protoType;
	/** 0-based index of this NodeInst in Cell. */			private int nodeIndex = -1;
	/** Array of PortInsts on this NodeInst. */				private PortInst[] portInsts = NULL_PORT_INST_ARRAY;

	/** bounds after transformation. */						private final Rectangle2D.Double visBounds = new Rectangle2D.Double(0, 0, 0, 0);
    /** True, if visBounds are valid. */                    private boolean validVisBounds;


    // --------------------- private and protected methods ---------------------

	/**
	 * The constructor of NodeInst. Use the factory "newInstance" instead.
     * @param d persistent data of this NodeInst.
	 * @param parent the Cell in which this NodeInst will reside.
	 */
    NodeInst(ImmutableNodeInst d, Cell parent) {
        super(parent);
        this.protoType = d.protoId.inDatabase(getDatabase());
        this.d = d;

        // create all of the portInsts on this node inst
		portInsts = new PortInst[protoType.getNumPorts()];
		for (int i = 0; i < portInsts.length; i++)
		{
			PortProto pp = protoType.getPort(i);
			portInsts[i] = PortInst.newInstance(pp, this);
		}
    }

    private NodeInst(NodeProto protoType, ImmutableNodeInst d) {
        super(null);
        assert d.protoId == protoType.getId();
        this.d = d;
        this.protoType = protoType;

        // create all of the portInsts on this node inst
		portInsts = new PortInst[protoType.getNumPorts()];
		for (int i = 0; i < portInsts.length; i++)
		{
			PortProto pp = protoType.getPort(i);
			portInsts[i] = PortInst.newInstance(pp, this);
		}
    }

    protected Object writeReplace() { return new NodeInstKey(this); }

    private static class NodeInstKey extends EObjectInputStream.Key<NodeInst> {
        public NodeInstKey() {}
        private NodeInstKey(NodeInst ni) { super(ni); }

        @Override
        public void writeExternal(EObjectOutputStream out, NodeInst ni) throws IOException {
            if (ni.getDatabase() != out.getDatabase() || !ni.isLinked())
                throw new NotSerializableException(ni + " not linked");
            out.writeObject(ni.getParent());
            out.writeInt(ni.getD().nodeId);
        }

        @Override
        public NodeInst readExternal(EObjectInputStream in) throws IOException, ClassNotFoundException {
            Cell cell = (Cell)in.readObject();
            int nodeId = in.readInt();
            NodeInst ni = cell.getNodeById(nodeId);
            if (ni == null)
                throw new InvalidObjectException("NodeInst from " + cell);
            return ni;
        }
    }

	/****************************** CREATE, DELETE, MODIFY ******************************/

	/**
	 * Short form method to create a NodeInst and do extra things necessary for it. Angle, name
	 * and techBits are set to defaults.
	 * @param protoType the NodeProto of which this is an instance.
	 * @param center the center location of this NodeInst.
	 * @param width the width of this NodeInst (can't be negative).
	 * @param height the height of this NodeInst (can't be negative).
	 * @param parent the Cell in which this NodeInst will reside.
     * @return the newly created NodeInst, or null on error.
	 */
	public static NodeInst makeInstance(NodeProto protoType, Point2D center, double width, double height, Cell parent)
	{
		return (makeInstance(protoType, center, width, height, parent, Orientation.IDENT, null, 0));
	}

	/**
	 * Long form method to create a NodeInst and do extra things necessary for it.
	 * @param protoType the NodeProto of which this is an instance.
	 * @param center the center location of this NodeInst.
	 * @param width the width of this NodeInst (can't be negative).
	 * @param height the height of this NodeInst (can't be negative).
	 * @param parent the Cell in which this NodeInst will reside.
	 * @param orient the orientation of this NodeInst.
	 * @param name name of new NodeInst
	 * @param techBits bits associated to different technologies
     * @return the newly created NodeInst, or null on error.
	 */
	public static NodeInst makeInstance(NodeProto protoType, Point2D center, double width, double height,
                                        Cell parent, Orientation orient, String name, int techBits)
	{
		NodeInst ni = newInstance(protoType, center, width, height, parent, orient, name, techBits);
		if (ni != null)
		{
			// set default information from the prototype
			if (protoType instanceof Cell)
			{
				// for cells, use the default expansion on this instance
				if (((Cell)protoType).isWantExpanded()) ni.setExpanded();
			} else
			{
				// for primitives, set a default outline if appropriate
				protoType.getTechnology().setDefaultOutline(ni);
			}

			// create inheritable variables
			CircuitChangeJobs.inheritAttributes(ni);
		}
		return ni;
	}

	/**
	 * Method to create a "dummy" NodeInst for use outside of the database.
	 * @param np the prototype of the NodeInst.
	 * @return the dummy NodeInst.
	 */
	public static NodeInst makeDummyInstance(NodeProto np)
	{
		return makeDummyInstance(np, EPoint.ORIGIN, np.getDefWidth(), np.getDefHeight(), Orientation.IDENT);
	}

	/**
	 * Method to create a "dummy" NodeInst for use outside of the database.
	 * @param np the prototype of the NodeInst.
	 * @param center the center location of this NodeInst.
	 * @param width the width of this NodeInst (can't be negative).
	 * @param height the height of this NodeInst (can't be negative).
	 * @param orient the orientation of this NodeInst.
	 * @return the dummy NodeInst.
	 */
	public static NodeInst makeDummyInstance(NodeProto np, EPoint center, double width, double height, Orientation orient)
	{
        EPoint size = EPoint.ORIGIN;
        if (np instanceof PrimitiveNode) {
            ERectangle full = ((PrimitiveNode)np).getFullRectangle();
            long gridWidth = DBMath.lambdaToSizeGrid(width - full.getLambdaWidth());
            long gridHeight = DBMath.lambdaToSizeGrid(height - full.getLambdaHeight());
            size = EPoint.fromGrid(gridWidth, gridHeight);
        }
        ImmutableNodeInst d = ImmutableNodeInst.newInstance(0, np.getId(), Name.findName("node@0"), TextDescriptor.getNodeTextDescriptor(),
                orient, center, size, 0,  0, TextDescriptor.getInstanceTextDescriptor());
        return new NodeInst(np, d);
	}

	/**
	 * Short form method to create a NodeInst. Angle, name
	 * and techBits are set to defaults.
	 * @param protoType the NodeProto of which this is an instance.
	 * @param center the center location of this NodeInst.
	 * @param width the width of this NodeInst (can't be negative).
	 * @param height the height of this NodeInst (can't be negative).
	 * If negative, flip the Y coordinate (or flip ABOUT the X axis).
	 * @param parent the Cell in which this NodeInst will reside.
     * @return the newly created NodeInst, or null on error.
	 */
	public static NodeInst newInstance(NodeProto protoType, Point2D center, double width, double height, Cell parent)
	{
		return (newInstance(protoType, center, width, height, parent, Orientation.IDENT, null, 0));
	}

	/**
	 * Long form method to create a NodeInst.
	 * @param protoType the NodeProto of which this is an instance.
	 * @param center the center location of this NodeInst.
	 * @param width the width of this NodeInst (can't be negative).
	 * @param height the height of this NodeInst (can't be negative).
	 * @param parent the Cell in which this NodeInst will reside.
	 * @param orient the oriantation of this NodeInst.
	 * @param name name of new NodeInst
	 * @param techBits bits associated to different technologies
     * @return the newly created NodeInst, or null on error.
	 */
	public static NodeInst newInstance(NodeProto protoType, Point2D center, double width, double height,
                                       Cell parent, Orientation orient, String name, int techBits)
	{
        if (name != null && parent.findNode(name) != null) {
            System.out.println(parent + " already has NodeInst with name \""+name+"\"");
            return null;
        }
        EPoint size = EPoint.ORIGIN;
        if (protoType instanceof PrimitiveNode) {
            ERectangle full = ((PrimitiveNode)protoType).getFullRectangle();
            long gridWidth = DBMath.lambdaToSizeGrid(width - full.getLambdaWidth());
            long gridHeight = DBMath.lambdaToSizeGrid(height - full.getLambdaHeight());
            size = EPoint.fromGrid(gridWidth, gridHeight);
        }
        return newInstance(parent, protoType, name, null, center, size, orient, 0, techBits, null, null);
	}

	/**
	 * Long form method to create a NodeInst.
	 * @param parent the Cell in which this NodeInst will reside.
	 * @param protoType the NodeProto of which this is an instance.
	 * @param name name of new NodeInst
     * @param nameDescriptor TextDescriptor of name of this NodeInst
	 * @param center the center location of this NodeInst.
	 * @param size the size of this NodeInst (can't be negative).
	 * @param orient the orientation of this NodeInst.
     * @param flags flags of this NodeInst.
	 * @param techBits bits associated to different technologies
     * @param protoDescriptor TextDescriptor of name of this NodeInst
     * @param errorLogger error logger to report node rename.
     * @return the newly created NodeInst, or null on error.
	 */
    public static NodeInst newInstance(Cell parent, NodeProto protoType,
                                       String name, TextDescriptor nameDescriptor,