PipalCore.mesa 
Copyright Ó 1986, 1987, 1988 by Xerox Corporation. All rights reversed.
Created by Bertrand Serlet August 6, 1986 0:38:23 am PDT
Bertrand Serlet May 8, 1988 0:33:25 am PDT
DIRECTORY
Core, CoreClasses, CoreFlat,
DABasics,
Pipal, PipalInt, PipalMos,
RefTab;
PipalCore: CEDAR DEFINITIONS IMPORTS Pipal = BEGIN
Theory
This interface defines how to attach geometry onto Core data structures. Geometry is represented using Pipal data types, for efficiency.
Two kinds of decorations are defined in this interface:
Interface decorations: The geometric interface of a decorated Core.CellType consists in its ports (attached on each public wire), and its object (the corresponding CD object).
Private decorations: Record cells and transistors record the geometry of the internal wires (but only the geometry found at that level), and record cells also record the geometrical transformation for each CellInstance.
Decorations
Decoration: TYPE = REF DecorationRec;
Decoration holds names of properties.
Should only be created by CreateDecoration
Definition of DecorationRec is only given for implementors' information. Access to all decorations should only be made via the procedural interface.
DecorationRec: TYPE = PRIVATE RECORD [
name: Core.ROPE,  -- Documentation purpose only
portProp: ATOM,  -- Hangs on each public wire to specify the ports of the public. Ports should be understood as the more general meaning of "interface geometry".
objectProp: ATOM,  -- Hangs on some cellTypes to specify the corresponding object. Currently only cellTypes of the recordCellClass and transistors have this decoration.
geometryProp: ATOM,  -- Hangs on every internal wires of record cellTypes to specify the geometry of the internal (but only at this level in the record).
transProp: ATOM  -- hangs on every CoreClasses.CellInstance of record cellTypes to specify the corresponding transformation.
];
layoutDecoration: Decoration;
schematicsDecoration: Decoration;
rawLayoutDecoration: Decoration;
CreateDecoration: PROC [name: Core.ROPE, coreSave: BOOL ← FALSE] RETURNS [decoration: Decoration];
Initializes of the fields of decoration properly.
All decorations must have different names (because properties atoms are computed using name).
Currently, the only clients are the one registering an extraction mode. A handle on an existing decoration can be found in an extraction mode.
Ports
In this section public stand for any wire, atomic or not, part of the public. All the functions of this section apply to publics of any cellType.
HasPort: PROC [decoration: Decoration, public: Core.Wire] RETURNS [BOOL];
Tests for public decorated.
GetPort: PROC [decoration: Decoration, public: Core.Wire] RETURNS [port: Pipal.Object ← Pipal.void];
PutPort: PROC [decoration: Decoration, public: Core.Wire, port: Pipal.Object];
Used for explicitly setting the port of a public. Previous port is discarded.
AddPort: PROC [decoration: Decoration, public: Core.Wire, port: Pipal.Object];
Used for explicitly adding a port to the one already on public. Might optimize the structure of the port object.
No action is taken if port=Pipal.void.
PutClippedPort: PROC [decoration: Decoration, public: Core.Wire, abutBox: PipalInt.Rectangle, subPort: Pipal.Object];
Optimizes the representation.
PutRecordPorts: PROC [decoration: Decoration, record: Core.CellType, abutBox: PipalInt.Rectangle];
Special speed-up of PutPort for ports that are obtained by following the bindings of a record.
It is assumed that the instances of the record are properly decorated.
Object
All the functions of this section apply to any cellType.
HasObject: PROC [decoration: Decoration, cellType: Core.CellType] RETURNS [BOOL];
GetObject: PROC [decoration: Decoration, cellType: Core.CellType] RETURNS [object: Pipal.Object];
PutObject: PROC [decoration: Decoration, cellType: Core.CellType, object: Pipal.Object];
Geometry
All the functions of this section apply to internals of record cells, or to publics of transistors.
HasGeometry: PROC [decoration: Decoration, wire: Core.Wire] RETURNS [BOOL];
Tests for wire decorated with at least an instance.
GetGeometry: PROC [decoration: Decoration, wire: Core.Wire] RETURNS [geometry: Pipal.Object ← Pipal.void];
PutGeometry: PROC [decoration: Decoration, wire: Core.Wire, geometry: Pipal.Object];
Used for explicitly setting geometry of a wire. Previous geometry discarded.
See further for lazyness.
AddGeometry: PROC [decoration: Decoration, wire: Core.Wire, geometry: Pipal.Object];
Used for explicitly adding geometry to the one already on wire.
See further for lazyness.
EachFlatWireProc: TYPE = PROC [wire: Core.Wire, flatWire: CoreFlat.FlatWireRec, trans: PipalInt.Transformation] RETURNS [quit: BOOL ← FALSE];
trans is the current transformation, expressed in the coordinate system of root, for flatCell.
flatWire is the canonized CoreFlat.FlatWireRec at the highest level that defines wire.
EachFlatCellProc: TYPE = PROC [bindings: CoreFlat.Bindings, cell: Core.CellType, flatCell: CoreFlat.FlatCellTypeRec, trans: PipalInt.Transformation] RETURNS [quit: BOOL ← FALSE];
bindings is a HashTable [public of cellType -> CoreFlat.FlatWire]. When cell=root, bindings=NIL
trans is the current transformation, expressed in the coordinate system of root, for flatCell.
LeafProc: TYPE = PROC [cellType: Core.CellType, bindings: CoreFlat.Bindings] RETURNS [BOOL];
TRUE stops enumeration and this cellType is not explored recursively.
EnumerateFlatGeometry: PROC [decoration: Decoration, root: Core.CellType, target: CoreFlat.FlatCellTypeRec ← CoreFlat.allFlatCells, leafProc: LeafProc, eachFlatWire: EachFlatWireProc ← NIL, eachFlatCell: EachFlatCellProc ← NIL] RETURNS [quit: BOOL];
Enumerates all wires and all instances under root.
When target is present, only enumerates wires and cells below target.
Call-back proc leafProc is called to direct recursion.
Call-back proc eachFlatWire gives as argument the geometry (transformed to be in root coordinate system). All enumerations are stopped if eachFlatWire RETURNS TRUE.
Call-back proc eachFlatCell gives as argument the current trans (transformed to be in root coordinate system). All enumerations are stopped if eachFlatWire RETURNS TRUE.
Instances can be enumerated more than once.
EnumerateAllGeometry: PROC [decoration: Decoration, cell: Core.CellType, wire: Core.Wire, each: PipalInt.EachChildProc, trans: PipalInt.Transformation] RETURNS [quit: BOOL];
Given a specified wire of cell, enumerates all the decorations (not always atomic, though) that comprise that wire.
Instances can be enumerated more than once.
GetAllGeometry: PROC [decoration: Decoration, cell: Core.CellType, wire: Core.Wire] RETURNS [geometry: Pipal.Object];
Inefficient proc for clients who really want to create all those instances obtained by EnumerateAllGeometry.
Transformation
All the functions of this section apply only to CellInstances of record cells.
HasTrans: PROC [decoration: Decoration, cellInstance: CoreClasses.CellInstance] RETURNS [BOOL];
For record decorations only.
GetTrans: PROC [decoration: Decoration, cellInstance: CoreClasses.CellInstance] RETURNS [trans: PipalInt.Transformation];
For record decorations only.
PutTrans: PROC [decoration: Decoration, cellInstance: CoreClasses.CellInstance, trans: PipalInt.Transformation];
For record decorations only.
Enumeration of Sides for Routers
These functions are not primitive, and are implemented using primitives of this interface. They are applicable for all Core data structures decorated with layout (not for structures not yet decorated), and should simplify the task of interfacing routers.
Port should be understand, for the following functions, in the sense of segment of interface geometry. Min and Max refer to the interesting projection in X or Y (depending on the side of the port), relatively to the InterestRect of the object. Note that the coordinate system is different from the other functions in this interface.
The only classes of decorations understood by these functions are rectangles, symbolic objects, atomic objects, and objects for which FlattenInstance is meaningful. Layers not registered with RegisterRoutingLayer are discarded.
Side: TYPE = DABasics.Side;
Sides: TYPE = DABasics.Sides;
noSide: Sides = DABasics.noSide;
RegisterRoutingLayer: PROC [layer: PipalMos.Layer];
GetSides: PROC [abutBox: PipalInt.Rectangle, trans: PipalInt.Transformation, port: Pipal.Object] RETURNS [sides: Sides ← noSide];
EachPinProc: TYPE = PROC [min, max: INT, side: Side, layer: PipalMos.Layer] RETURNS [quit: BOOL ← FALSE];
EnumerateSides: PROC [decoration: Decoration, cellType: Core.CellType, wire: Core.Wire, eachPin: EachPinProc] RETURNS [quit: BOOL];
Enumerates all the pins for wire.
EachWirePinProc: TYPE = PROC [wire: Core.Wire, min, max: INT, side: Side, layer: PipalMos.Layer] RETURNS [quit: BOOL ← FALSE];
EnumerateWireSides: PROC [decoration: Decoration, cellType: Core.CellType, eachWirePin: EachWirePinProc] RETURNS [quit: BOOL];
Enumerates all the pins of the public wires of cellType.
May enumerate several times the overlapping segments.
EnumerateNonOverlappingSides: PROC [decoration: Decoration, cellType: Core.CellType, eachWirePin: EachWirePinProc] RETURNS [quit: BOOL];
Enumerates all the pins of the public wires of cellType, but enumerates once only segments that overlap.
EachSortedPinProc: TYPE = PROC [wire: Core.Wire, min, max: INT, layer: PipalMos.Layer] RETURNS [quit: BOOL ← FALSE];
EnumerateSortedSides: PROC [decoration: Decoration, cellType: Core.CellType, side: Side, eachSortedPin: EachSortedPinProc] RETURNS [quit: BOOL];
Enumerates all the pins of all the wires for cellType. Segments are enumerated in increasing min order.
Fabrication of Shells for Routers or for IO
This function is also not primitive, but can be used by several different programs.
CreateShell: PROC [decoration: Decoration, cellType: Core.CellType, withCuteFonts: BOOL ← FALSE] RETURNS [shell: Pipal.Object];
Creates a CD cell that contains instances which correspond to the ports of the publics of cellType. Each CD instance has an $SignalName property which is the (public) full name of the wire.
Parameter withCuteFonts provokes, when TRUE, creation of text in front of each instance.
The shell has an InterestRect of the same size as the cellType interestRect.
Checking of Decorations
CheckInterface: PROC [decoration: Decoration, cellType: Core.CellType] RETURNS [ok: BOOL];
Checks that cellType has a object and that all its atomic public are decorated.
CheckInternal: PROC [decoration: Decoration, record: Core.CellType] RETURNS [ok: BOOL];
Checks that all the atomic public are decorated, and that each cell instance has a transformation.
Neighbors
EnumerateNeighbors: PROC [decoration: Decoration, touch: PipalMos.TouchProc, inX: BOOL, ct1, ct2: Core.CellType, eachPair: PROC [Core.Wire, Core.Wire] RETURNS [quit: BOOL ← FALSE]] RETURNS [BOOL];
Enumerate all pairs of public for which some port of ct1 touches some port of ct2, after the appropriate transformation.
Pairs might be enumerated multiple times.
Not very efficient for numerous decorations.
WirePair: TYPE = RECORD [wire1, wire2: Core.Wire];
CreateNeighborsCache: PROC RETURNS [cache: RefTab.Ref];
Creates a Cache for CachedEnumerateNeighbors
CachedEnumerateNeighbors: PROC [decoration: Decoration, touch: PipalMos.TouchProc, inX: BOOL, ct1, ct2: Core.CellType, cache: RefTab.Ref] RETURNS [LIST OF WirePair];
Same as EnumerateNeighbors, but uses a global cache for neighbors.
Pairs are unique within the list.
END.