scanchainxml.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: ScanChainXML.java
 *
 * Copyright (c) 2005 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.tool.io.output;

import com.sun.electric.database.hierarchy.*;
import com.sun.electric.database.topology.NodeInst;
import com.sun.electric.database.topology.PortInst;
import com.sun.electric.database.topology.ArcInst;
import com.sun.electric.database.topology.Connection;
import com.sun.electric.database.network.Netlist;
import com.sun.electric.database.network.Network;
import com.sun.electric.database.prototype.NodeProto;
import com.sun.electric.database.prototype.PortProto;
import com.sun.electric.database.text.Name;

import java.util.*;
import java.io.*;

/**
 * Class to define XML for scan chains.
 */
public class ScanChainXML {

    private static final boolean DEBUG = false;
    private static final boolean FLAT = false;
    private static final boolean REDUCE = true;
    
    private static Netlist.ShortResistors SHORT_RESISTORS = Netlist.ShortResistors.PARASITIC;

    // --------------------------- Scan Chain Primitives -----------------------------

    /** Defines a Scan Chain Element, which contains one bit of scan storage */
    private static class ScanChainElement {
        public final String name;
        public final String access;
        public final String clears;
        public final String inport;
        public final String outport;
        public final DataNet dataport;
        public final DataNet dataport2;

        private ScanChainElement(String name, String access, String clears, String inport,
                                 String outport, String dataport, String dataport2) {
            this.name = name;
            this.access = access;
            this.clears = clears;
            this.inport = inport;
            this.outport = outport;
            if (dataport == null || dataport.equals(""))
                this.dataport = null;
            else
                this.dataport = new DataNet(dataport);
            if (dataport2 == null || dataport2.equals(""))
                this.dataport2 = null;
            else
                this.dataport2 = new DataNet(dataport2);
        }
    }

    private static class DataNet {
        public final String net;
        public final String options;        // options including parenthesis

        /**
         * Creates a data net object that describes a net that is written or read
         * to by a scan chain element.
         * @param netName the name of the data net, including any options prepended
         * in parenthesis. R for readable, W for writeable, I for inverted.
         * Ex: net26 or net26(R) or net26(RWI).
         */
        public DataNet(String netName) {
            int i = netName.indexOf('(');
            if (i != -1) {
                net = netName.substring(0, i);
                options = netName.substring(i, netName.length());
            } else {
                net = netName;
                options = "";
            }
        }

        /**
         * Creates a data net object that describes a net that is written or read
         * to by a scan chain element.
         * @param net the net name
         * @param options options describing the network: R for readable, W for
         * writable, I for inverted. Should be encased in parenthesis, such as
         * (RW).
         */
        public DataNet(String net, String options) {
            this.net = net;
            this.options = options;
        }

        public String toString() { return net+options; }
    }

    /** Defines the Jtag controller from which the scan chains start and end */
    private static class JtagController {
        public final String name;
        public final int lengthIR;
        private List<Port> ports;

        protected static class Port {
            public final int opcode;
            public final String soutPort;
            public final String chainName;
            public Port(int opcode, String soutPort, String chainName) {
                this.opcode = opcode;
                this.soutPort = soutPort;
                this.chainName = chainName;
            }
        }

        private JtagController(String name, int lengthIR) {
            this.name = name;
            this.lengthIR = lengthIR;
            ports = new ArrayList<Port>();
        }

        /**
         * Add an opcode for a chain, and the associated scan out port,
         * for example addPort(1, "leaf1[0]")
         * @param opcode the opcode of the chain
         * @param soutPort the associated scan out port
         */
        private void addPort(int opcode, String soutPort, String chainName) {
            Port p = new Port(opcode, soutPort, chainName);
            ports.add(p);
        }
        /** get iterator over JtagContoller.Port list */
        private Iterator<Port> getPorts() { return ports.iterator(); }
    }

    /**
     * Define a pass through cell that passes scan data through it.  Examples
     * are inverters or buffers.
     */
    private static class PassThroughCell {
        public final String cellName;
        public final String inport;
        public final String outport;

        public PassThroughCell(String cellName, String inport, String outport) {
            this.cellName = cellName;
            this.inport = inport;
            this.outport = outport;
        }
    }

    // --------------------------------------------------------------------

    private String outputFile;
    private PrintWriter out;
    private File outFile;
    // objects used to parse cell schematics
    private JtagController jtagController;
    private HashMap<String,ScanChainElement> scanChainElements;
    private HashMap<String,PassThroughCell> passThroughCells;
    private HashMap<Cell,Cell> cellsToFlatten;
    private String chipName;
    private Cell jtagCell;
    // list of parsed objects to write to XML
    private Map<String,Entity> entities;                          // list of !ENTITY definitions
    private List<Chain> chains;                            // list of top level chains
    private SubChain endChain;

    // for tracing one subchain
    private List<String> chainStartExports = null;          // list of strings
    private List<String> chainNames = null;                 // list of strings
    private List<ExPort> chainStartExPorts = null;          // list of ExPorts

    // ------------------------ Constructors ------------------------------

    /**
     * Create a new ScanChainXML object that will parse the schematics and
     * write out an XML description
     */
    public ScanChainXML() {
        this.jtagController = null;
        this.scanChainElements = new HashMap<String,ScanChainElement>();
        this.passThroughCells = new HashMap<String,PassThroughCell>();
        this.cellsToFlatten = new HashMap<Cell,Cell>();
        this.chipName = "?";
        this.jtagCell = null;
        outputFile = null;
        out = new PrintWriter(System.out);
        outFile = null;
        entities = new HashMap<String,Entity>();
        chains = new ArrayList<Chain>();
    }

    // --------------------------- Settings --------------------------------

    /**
     * Specify a scan chain element.  When an instance of this is found, it is will
     * be parsed as one bit in the scan chain.
     * @param name name of the cell to be defined as a scan chain element.
     * @param access the access type: for example, "RW".
     * @param clears the clears type: for example, "L".
     * @param inport the name of input data port, typically "sin".
     * May contain index info, such as "s[1]"
     * @param outport the name of the output data port, typically "sout".
     * May contain index info, such as "ss[1]"
     */
    public void addScanChainElement(String name, String access, String clears, String inport, String outport) {
        ScanChainElement e = new ScanChainElement(name, access, clears, inport, outport, "", "");
        scanChainElements.put(name+"_"+inport, e);
    }

    /**
     * Specify a scan chain element.  When an instance of this is found, it is will
     * be parsed as one bit in the scan chain.
     * @param name name of the cell to be defined as a scan chain element.
     * @param access the access type: for example, "RW".
     * @param clears the clears type: for example, "L".
     * @param inport the name of input data port, typically "sin".
     * May contain index info, such as "s[1]"
     * @param outport the name of the output data port, typically "sout".
     * May contain index info, such as "ss[1]"
     * @param dataport the name of the port the scan data is read from and written to. May include options
     * R, W, or I for (Readable,Writable,Inverted) in parenthesis at the end. Ex: dout(RW)
     * @param dataport2 another port for data like dataport, with the same format.
     */
    public void addScanChainElement(String name, String access, String clears, String inport, String outport, String dataport, String dataport2) {
        ScanChainElement e = new ScanChainElement(name, access, clears, inport, outport, dataport, dataport2);
        scanChainElements.put(name+"_"+inport, e);
    }

    /**
     * Specify a pass through element.  Pass through elements are found in series in
     * the scan chain, but are not scan chain elements themselves.  Examples of this are
     * inverters and buffers that buffer the scan chain data.
     * @param cellName name of the cell to be defined as a pass through element
     * @param inport the name of the input port that passes data through
     * May contain index info, such as "s[1]"
     * @param outport the name of the output port that passes data through
     * May contain index info, such as "ss[1]"
     */
    public void addPassThroughCell(String cellName, String inport, String outport) {
        PassThroughCell p = new PassThroughCell(cellName, inport, outport);
        passThroughCells.put(cellName+"_"+inport, p);
    }

    /**
     * Specify a cell to flatten.  The XML is hierarchical, but sometimes you don't need
     * or want all that hierarchy.  This specifies a cell that will be flattened
     * @param libName the library that contains the cell
     * @param cellName the name of the cell
     */
    public void addCellToFlatten(String libName, String cellName) {
        //System.out.println("Warning: addCellToFlatten() optimization is no longer supported.");
        Library lib = Library.findLibrary(libName);
        if (lib == null) {
            System.out.println("Did not find library "+libName+" for flattening cell "+cellName);
            return;
        }
        Cell cell = lib.findNodeProto(cellName);
        if (cell == null) {
            System.out.println("Did not find cell "+cellName+" to flatten, in library "+libName);
            return;
        }
        cellsToFlatten.put(cell, cell);
    }

    /**
     * Specify the JTAG Controller.  All scan chains are assumed to start, and end, at the
     * JTAG Controller.  This specifies the jtag controller.
     * @param jtagLib the name of the library that holds the jtag controller cell
     * @param jtagCellName the name of the cell that is the jtag controller
     * @param lengthIR the number of instruction register bits in the jtag controller.
     */
    public void setJtagController(String jtagLib, String jtagCellName, int lengthIR) {
        Library lib = Library.findLibrary(jtagLib);
        if (lib == null) {
            System.out.println("Did not find jtag library "+jtagLib);
            return;
        }
        Cell cell = lib.findNodeProto(jtagCellName);
        if (cell == null) {
            System.out.println("Did not find jtag cell "+jtagCellName+" in library "+jtagLib);
            return;
        }
        jtagCell = cell;
        jtagController = new JtagController(jtagCellName, lengthIR);
        //PassThroughCell endCell = new PassThroughCell(jtagCellName, null, null);
        endChain = new SubChain("end:jtagController", -1);
    }

    /**
     * Add a port to the JTAG Controller that serves as a starting point for a scan chain.
     * A JTAG Controller may have several ports that each have a scan chain attached.
     * The JTAG Controller must have already been specified using setJtagController.
     * @param opcode the opcode for this scan chain
     * @param soutPortName the port name that outputs data for the scan chain.
     * May contain index info, such as "leaf1[1]"
     * @param chainName the name given to this scan chain
     */
    public void addJtagPort(int opcode, String soutPortName, String chainName) {
        if (jtagController == null) {
            System.out.println("Can't add port "+soutPortName+" because the jtag controller has not been defined yet");
            return;
        }
        jtagController.addPort(opcode, soutPortName, chainName);
    }

    /**
     * Start tracing a chain from the specified export in the start cell.  This
     * is used to trace a section of the scan chain. This
     * traces only one chain.
     * @param exportName
     * @param chainName
     */
    public void startFromExport(String exportName, String chainName) {
        if (chainStartExports == null) {
            chainStartExports = new ArrayList<String>();
            chainNames = new ArrayList<String>();
            chainStartExPorts = new ArrayList<ExPort>();
        }
        chainStartExports.add(exportName);
        chainNames.add(chainName);
    }

    /**
     * Specify the name of the chip. Only used when writing the chip name to the file.
     * @param name the chip name
     */