EXTFLAT(3)

NAME
extflat - procedures in libextflat.a for flattening extractor .ext files

SYNOPSIS

#include "hash.h"
#include "extflat.h"

typedef struct hiername { ... } HierName;
typedef struct efnn { ... } EFNodeName;
typedef struct efnhdr { ... } EFNodeHdr;
typedef struct efnode { ... } EFNode;
typedef struct fet { ... } Fet;
EFInit()
EFDone()
char *
EFArgs(argc, argv, argsProc, cdata)
    int argc;
    char *argv[];
    Void (*argsProc)(pargc, pargv, cdata);
    ClientData cdata;
EFReadFile(name)
    char *name;
EFFlatBuild(rootName, flags)
    char *rootName;
    int flags;
EFFlatDone()
EFVisitCaps(capProc, cdata)
    int (*capProc)(hn1, hn2, double cap, cdata);
    ClientData cdata;
EFVisitFets(fetProc, cdata)
    int (*fetProc)(fet, prefix, trans, cdata)
    ClientData cdata;
EFVisitNodes(nodeProc, cdata)
    int (*nodeProc)(node, int r, double c, cdata);
    ClientData cdata;
int
EFNodeResist(node)
    EFNode *node;
EFVisitResists(resProc, cdata)
    int (*resProc)(hn1, hn2, res, cdata);
    ClientData cdata;
bool
EFLookDist(hn1, hn2, pMinDist, pMaxDist)
    HierName *hn1, *hn2;
    int *pMinDist, *pMaxDist;
char *
EFHNToStr(hn)
    HierName *hn;
HierName *
EFStrToHN(prefix, suffixStr)
    HierName *prefix;
    char *suffixStr;
HierName *
EFHNConcat(prefix, suffix)
    HierName *prefix, *suffix;
HashEntry *
EFHNLook(prefix, suffixStr, errorStr)
    HierName *prefix;
    char *suffixStr;
    char *errorStr;
HashEntry *
EFHNConcatLook(prefix, suffix, errorStr)
    HierName *prefix, *suffix;
    char *errorStr;
EFHNOut(hn, outf)
    HierName *hn;
    FILE *outf;
EFHNFree(hn, prefix, type)
    HierName *hn, *prefix;
    int type;
bool
EFHNBest(hn1, hn2)
    HierName *hn1, *hn2;
bool
EFHNIsGND(hn)
    HierName *hn;
bool
EFHNIsGlob(hn)
    HierName *hn;
typedef struct hiername { ... } HierName;
typedef struct efnn { ... } EFNodeName;
typedef struct efnhdr { ... } EFNodeHdr;
typedef struct efnode { ... } EFNode;
typedef struct fet { ... } Fet;

DESCRIPTION
This module provides procedures for reading, flattening, and traversing the hierarchical extracted circuits (in ext(5) format) produced by the Magic circuit extractor.

To use the procedures in this library, a client should first call EFInit to initialize various hash tables. When a client is finally finished with this library, and wishes to free up any remaining memory used by it, EFDone should be called.

COMMAND-LINE ARGUMENT PROCESSING
The procedure EFArgs is provided for parsing of command-line flags; it should be passed the arguments to main. It will scan through them, recognizing those specific to extflat (see extcheck(1) for a list of these arguments) and passing unrecognized arguments to the user-supplied procedure argsProc, which should update *pargc and *pargv to point after each argument it recognizes, or else print an error message if the argument is unrecognized. If it is necessary to pass any additional information to argsProc, the cdata argument of EFArgs is automatically passed as the third argument to argsProc. If argsProc is NULL, any arguments not recognized by EFArgs are considered to be errors. EFArgs considers any argument not beginning with a dash (``-'') to be a filename, of which there can be at most one. The argument containing this filename is returned to the caller.

FLATTENING A CIRCUIT
Once command-line argument processing is complete, the caller can cause ext(5) files to be read by calling EFReadFile. This procedure will read name.ext and all of the .ext files it refers to, recursively until the entire tree rooted at name has been read and converted into an internal, hierarchical representation. EFReadFile may be called several times with different values of name; any portions of the tree rooted at name that aren't already read in will be.

To build up the flat representation of a circuit read using EFReadFile one should call EFFlatBuild. The argument rootName gives the name of the cell, which should have been read with EFReadFile above, that is the root of the hierarchical circuit to be flattened. After all subsequent processing of the flat design is complete, the caller may call EFFlatDone to free the memory associated with the flattened circuit, possibly in preparation for calling EFFlatBuild with a different rootName.

A different procedure is provided for visiting all of the structures of each type in the flattened circuit: EFVisitCaps, EFVisitFets, EFVisitNodes, and EFVisitResists. Each takes two arguments: a search procedure to apply to all structures visited, and a ClientData field used to pass additional information to this search procedure.

EFVisitCaps visits each of the internodal capacitors in the flat circuit, applying capProc to each. The arguments to capProc are the HierNames hn1 and hn2 of the two nodes between which the capacitor sits, the capacitance cap in attofarads (type double from 6.5 and later), and the client data cdata with which EFVisitCaps was called. If it's necessary to obtain a pointer to the flat EFNode structures to which hn1 or hn2 refer, they can be passed to EFHNLook (see below).

EFVisitFets visits each of the transistors in the circuit, applying fetProc to each. The arguments to fetProc are the transistor structure itself, fet, the hierarchical path prefix that should be prepended to the node names of all the fet's terminals, a geometric transform that must be applied to all coordinates in the fet to convert them to root coordinates, the computed length l and width w of the transistor channel (taking into account substitution of symbolic values with the -s flag), and the client data cdata with which EFVisitFets was called.

EFVisitNodes visits each of the flat nodes in the circuit, applying nodeProc to each. The arguments to nodeProc are the flat EFNode node, its lumped resistance r and capacitance to substrate c (r type is integer and c type is double from 6.5 and later), and the client data cdata with which EFVisitNodes was called. An auxiliary procedure, EFNodeResist, is provided to compute the lumped resistance of a node from the perimeter and area information stored in it; it returns the resistance estimate in milliohms.

EFVisitResists visits each of the explicit resistors in the circuit, applying resProc to each. The arguments to resProc are similar to those of capProc: the HierNames hn1 and hn2 of the two terminals of the resistor, its resistance res, and the client data cdata with which EFVisitResists was called.

A final procedure is provided for looking up distance information. EFLookDist searches to find if there was a distance measured between the points with the HierNames hn1 and hn2. If there was a distance found, it returns TRUE and leaves *pMinDist and *pMaxDist set respectively to the minimum and maximum measured distance between the two points; otherwise, it returns FALSE.

NODE ORGANIZATION
Each electrical node in the circuit is represented by an EFNode structure, which points to a NULL-terminated list of EFNodeNames, each of which in turn points to the HierName list representing the hierarchical name. EFNodes contain capacitance, perimeter, and area information for a node. If this information is not required, an application may use EFNodeHdr structures in place of EFNodes in many cases; an EFNodeHdr consists of just the first few fields of an EFNode. Each EFNodeName is pointed to by a HashEntry in a hash table of all flattened node names.

HIERARCHICAL NAME MANIPULATION
Hierarchical node names are represented as lists of HierName structures. These structures store a hierarchical pathname such as foo/bar[1][3]/bletch in reverse order, with the last component (e.g., bletch) first. Pathnames sharing a common prefix can therefore be shared.

EFStrToHN is the fundamental procedure for creating HierNames; it builds a path of HierNames from the string suffixStr, and then leaves this path pointing to the prefix path prefix. For example, if prefix were the path of HierNames representing foo/bar[1][3], and suffix were the string shift/Vb1, the resulting HierName would be foo/bar[1][3]/shift/Vb1, but only the shift/Vb1 part would be newly allocated. EFHNFree frees the memory allocated for the portions of the HierName path pointed to by hn between hn and prefix, which should be the same as the prefix passed to EFStrToHN. The type parameter is used only for measuring memory usage and should be zero. EFHNToStr converts a HierName back into a string; it returns a pointer to a statically-allocated copy of the string representation of the HierName hn.

EFHNConcat is like EFStrToHN in that it concatenates a prefix and a suffix, but the suffix passed to EFHNConcat has already been converted to a HierName. EFHNConcat creates a copy of the HierName path suffix whose final element points to the prefix prefix, in effect producing the concatenation of the two HierNames.

EFHNLook finds the HashEntry in the flat node hash table corresponding to the HierName that is the concatenation of the HierName prefix and the HierName formed from the suffix string suffixStr. The value field of this HashEntry (obtained through HashGetValue) is a pointer to an EFNodeName, which in turn points to the EFNode for this name. EFHNLook returns NULL if there wasn't an entry in the node hash table by this name, and also prints an error message of the form ``errorStr: node prefix/suffixStr not found''. EFHNConcatLook performs a similar function, but its second argument is a HierName instead of a string.

EFHNOut writes the HierName hn to the output FILE *outf. The -t flag can be passed to EFArgs to request suppression of trailing ``!'' or ``#'' characters in node names when they are output by EFHNOut.

Three predicates are defined for HierNames. EFHNBest returns TRUE if hn1 is ``preferred'' to hn2, or FALSE if the opposite is true. Global names (ending in ``!'') are preferred to ordinary names, which are preferred to automatically-generated names (ending in ``#''). Among two names of the same type, the one with the least number of pathname components is preferred. If two names have the same number of components, the one lexicographically earliest is preferable. EFHNIsGND returns TRUE if its argument is the ground node ``GND!''. EFHNIsGlob returns TRUE if its argument is a global node name, i.e., ends in an exclamation point.

SEE ALSO
extcheck(1), ext2dlys(1), ext2sim(1), ext2spice(1), magic(1) magicutils(3), ext(5)