There is an internal data structure for saving information from a cell
hierarchy in compact form. This is accessible from a set of script
functions described below.
This allows very large data files to be scanned, and opened in
skeleton mode. When opening a file in skeleton mode in the ``normal''
way, the entire hierarchy of cells and instances is saved, minus only
the geometry. One could still run out of memory with large
hierarchies, since all cells/instances are saved, whether used or not,
and the main database is not efficient for storing the limited
information really needed. The functions below get around this by
pruning the skeleton to only the cells/instances actually needed to
represent the data window before creating the in-memory hierarchy.
This capability applies to physical data only, and the following
script functions expose the implementation. Note that there is a
handle type to support this data structure.
- (string) FileInfo(filename, handle_or_filename,
flags)
This function provides information about the archive file given by the
first argument. If the second argument is a string giving the name of
a file, output will go to that file. If the second argument is a
handle returned from the Open function or similar (opened for
writing), output goes to the handle stream. In either case, the
return value is a null string. If the second argument is a scalar 0,
the output will be in the form of a string which is returned.
The third argument is an integer whose bits are flags that represent
the type of information to return. See the description of the CxInfo function for information about these flags and the
corresponding output.
This function is similar to the !fileinfo command.
- (cx_handle) GetArchiveContext(filename, scale,
save_pcinfo)
This function returns a handle to a context representation obtained
from the archive file given as the argument. The file is opened from
the library search path, if a full path is not provided. The context
representation is a data structure that provides information about the
hierarchy in compact form, and does not use that main database. The
second argument is a scale factor that will be applied as the file is
read, and must be between .001 and 1000. The third argument is a
boolean that causes the context to store extra per-cell information.
This information is used by the CxEstFlatMemoryUse function, and
the argument should be nonzero if this function is going to be used
with the returned context. Otherwise, the third argument can be zero.
If a boolean true is passed for save_pcinfo, then the counts
reported by CxInfo in the context represent only those objects
on layers that pass any layer filtering from the LayerList/UseLayerList variables. Furthermore, in this case, the cell bounding
boxes represent only objects on these layers, and subcells. In this
mode, any read with the context should use the same layer filtering,
or the bounding boxes of cells in memory won't match those computed in
the context. The CxEstFlatMemoryUse function will report only
the size potentially occupied by objects on these layers. If this
argument is false, the counts and bounding boxes represent all layers,
i.e., layer filtering is ignored.
The returned handle can be passed to other functions that require this
data type. The Close function can be used to delete the context
structure and free the handle.
The names of cells saved in the context reflect any aliasing that was
in force at the time the context was created. The applicable aliasing
is the same as if the file is read into memory with the Conversion - Import panel in the Convert Menu.
The random-access capability of cells through the context can be
very slow if the file is compressed.
- (int) SaveArchiveContext(cx_handle, name)
Store the context into a database, keyed by name. The name is an arbitrary short string, for example the file name. The
context will remain in program memory until it is explicitly removed,
or ClearAll is called. Contexts that are not saved are
destroyed when the handle is closed, or the script terminates. A
context can not be stored more than once, and the name must not
already be in use for context storage. The function returns 1 if the
context was successfully stored, 0 otherwise with possibly an error
message retrievable with GetError.
- (cx_handle) RecallArchiveContext(name, remove)
Recall a context from the database (as saved with SaveArchiveContext) and return a handle to it. If the integer remove is nonzero, it is removed from the database, otherwise not. A
scalar 0 is returned if the context is not found or some other error
occurs.
- (int) WriteArchiveContext(cx_handle, filename)
This function will write a disk file representation of the archive
context associated with the handle, into the file whose name is given
as the second argument. Subsequently, the file can be read with ReadArchiveContext to recreate the context. The file has no other
use and the format is not documented.
The archive context (and thus the file) contains offsets onto the
target archive, as well as the archive location. There is no checksum
or other protection currently, so it is up to the user to make sure
that the target archive is not moved or modified while the context is
potentially or actually in use.
The function returns 1 if the file was written successfully, 0
otherwise, with an error message likely available from GetError.
- (int) ReadArchiveContext(filename)
This function returns a handle to an archive context created from the
file whose name is passed as an argument. The file must have been
created with WriteArchiveContext. On error, a scalar 0 is
returned, with an error message probably available from GetError.
- (string) CxInfo(cx_handle, handle_or_filename,
flags)
This function provides information about the context indicated by the
first argument. If the second argument is a string giving the name of
a file, output will go to that file. If the second argument is a
handle returned from the Open function or similar (opened for
writing), output goes to the handle stream. In either case, the
return value is a null string. If the second argument is a scalar 0,
the output will be in the form of a string which is returned.
The third argument is an integer whose bits are flags that represent
the type of information to return. If this value is 0, all flags
except for INFO_FLAGS will be taken as set. Otherwise the
returned information will contain fields associated with the set bits:
Flag Name |
Value |
Description |
INFO_FILENAME |
0x1 |
File name. |
INFO_FILETYPE |
0x2 |
File type (``CIF'', ``CGX'',
``GDSII'', or ``OASIS''). |
INFO_OBJCOUNTS |
0x4 |
Table of object counts. |
INFO_RECCOUNTS |
0x8 |
Table of record type counts (file format
dependent). |
INFO_ESTSIZE |
0x10 |
Print estimated memory needed to read file
into Xic. |
INFO_ESTCXSIZE |
0x20 |
Print size of data structure used to
provide info. |
INFO_ESTSKSIZE |
0x40 |
Estimated memory required for
skeleton. |
INFO_LAYERS |
0x80 |
List of layer names found, as for CxLayers
function. |
INFO_TOPCELLS |
0x100 |
Top-level cells. |
INFO_ALLCELLS |
0x200 |
All cells. |
INFO_OFFSORT |
0x400 |
Sort cells by offset in archive file. |
INFO_OFFSET |
0x800 |
Print offsets of cell definitions in archive
file. |
INFO_INSTANCES |
0x1000 |
List instances with cells. |
INFO_BBS |
0x2000 |
List bounding boxes with cells, and attributes
with instances. |
INFO_FLAGS |
0x4000 |
List flags with cells and instances. |
INFO_DEPTHCNTS |
0x8000 |
Tabulate the number of cell instances
at each hierarchy level. |
INFO_UNRESOLVED |
0x10000 |
List any cells that are referenced
but not defined in the file. |
The information provided by these flags is more fully described below.
- INFO_FILENAME
Print the name of the archive file for which the information applies.
- INFO_FILETYPE
Print a string giving the format of the archive file: one of ''CIF'', ``CGX'', ``GDSII'', or ``OASIS''.
- INFO_OBJCOUNTS
Print a table of object counts found in the archive file. The table
contains the following keywords, each followed by a number.
Keyword |
Descripption |
Records |
Total record count |
Symbols |
Number of cell definitions |
Boxes |
Number of rectangles |
Polygons |
Number of polygons |
Wires |
Number of wire paths |
Avg Verts |
Average vertex count per poly or wire |
Labels |
Number of (non-physical) labels |
Srefs |
Number of non-arrayed instances |
Arefs |
Number of arrayed instances |
- INFO_RECCOUNTS
Print a table of the counts for record types found in the archive.
This is format-dependent.
- INFO_ESTSIZE
This flag will enable printing of the estimated memory required to
read the entire file into Xic. The system must be able to provide
at least this much memory for a read to succeed.
- INFO_ESTCXSIZE
Xic uses an ``archive context'' data structure to hold information
after scanning a file. This data structure has many uses. If this
flag is set, an estimate of the size of this data structure is
printed.
- INFO_ESTSKSIZE
Print an estimate of the memory needed to read the archive in skeleton
mode. This is the memory space used to hold the cell/instance
hierarchy, without geometry.
- INFO_LAYERS
Print a list of the layer names encountered in the archive, as for
the CxLayers function.
- INFO_TOPCELLS
List the top-level cells, i.e., the cells in the file that are not
used as a subcell by another cell in the file. If INFO_ALLCELLS is also given, only the names are listed, otherwise
the cells are listed including the INFO_OFFSET, INFO_INSTANCES, INFO_BBS, and INFO_FLAGS fields if
these flags are set. The list will be sorted as per INFO_OFFSORT.
- INFO_ALLCELLS
All cells found in the file are listed by name, including the INFO_OFFSET, INFO_INSTANCES, INFO_BBS, and INFO_FLAGS fields if these flags are also given. The list will be
sorted as per INFO_OFFSORT.
The following flags apply only if at least one of INFO_TOPCELLS
or INFO_ALLCELLS is given.
- INFO_OFFSORT
If this flag is set, the cells will be listed in ascending order of
the file offset, i.e., in the order in which the cell definitions
appear in the archive file. If not set, cells are listed
alphabetically.
- INFO_OFFSET
When set, the cell name is followed by the offset of the cell
definition record in the archive file. This is given as a decimal
number enclosed in square brackets.
- INFO_INSTANCES
For each cell, the subcells used in the cell are listed. The subcell
names are indented and listed below the cell name.
- INFO_BBS
For each cell the bounding box is shown, in L,B R,T form. For
subcells, the position, transformation, and array parameters are
shown. Coordinates are given in microns. The subcell transformation
and array parameters are represented by a concatenation of the
following tokens, which follow the subcell reference position. These
are similar to the transformation tokens found in CIF, and have the
same meanings.
MY |
Mirror about the x-axis. |
Ri,j |
Rotate by an angle given by the vector
i,j. |
Mmag |
Magnify by mag. |
Anx,ny,dx,dy |
Specifies an array,
nx x ny with spacings dx, dy. |
- INFO_FLAGS
For cells, the ``area_ok'' flag is shown. This will be set when the
area configuration has been applied (with CxSetArea), and the
cell is included within the hierarchy needed to represent the
configured area. This will be zero in FileInfo and similar
calls.
For instances, a similar flag is shown. If set, the instance is
included in the configuration area. This will be zero in FileInfo and similar calls.
- INFO_DEPTHCNTS
A table of the number of cell instantiations at each hierarchy level
is printed, for each top-level cell found in the file. The count for
depth 0 is 1 (the top-level cell), the count at depth 1 is the number
of subcells of the top-level cell, depth 2 is the number of subcells
of these subcells, etc. Arrays are given one count, the same as a
single instance.
- INFO_UNRESOLVED
This will list cells that are referenced but not defined in the file.
These will also be listed if INFO_ALLCELLS is given. A valid
archive file will not contain unresolved references.
This function is very similar to FileInfo.
- (real) CxEstFlatMemoryUse(cx_handle, cellname,
array, counts_array)
This function will return an estimate of the memory required to
perform a CxOpenFlat call. The first argument must have been
obtained from a GetArchiveContext call with the save_pcinfo argument set true (nonzero). The second argument is the
name of the cell in the context to take as the top-level cell. If 0
is passed for this argument, the top-level cell of the context which
appears first in the archive file will be used.
The third argument is an array of size four or larger that contains
the rectangular area as passed to the CxOpenFlat call. The
components are
array[0] |
X left |
array[1] |
Y bottom |
array[2] |
X right |
array[3] |
Y top |
This argument can also be zero to indicate that the full area of the
top level cell is to be considered.
The final argument is also an array of size four or larger, or zero.
If an array is passed, and the function succeeds, the components are
filled with the following values:
counts_array[0] |
estimated total box count |
counts_array[1] |
estimated total polygon count |
counts_array[2] |
estimated total wire count |
counts_array[3] |
estimated total vertex count |
These are counts of objects that would be saved in the top-level cell
during the CxOpenFlat call. These are estimates, based on area
normalization, and do not include any clipping or merging. The vertex
count is an estimate of the total number of polygon and wire vertices.
The return value is an estimate, in megabytes, of the incremental
memory required to perform the CxOpenFlat call. This does not
include normal overhead.
- (int) CxCompare(cx_handle1, cx_handle,
cellname, layer_list, obj_types,
skip_layers, geometric, array)
This will compare the contents of the given cell, somewhat similar to
the !compare command, but unlike the command, only one cell is
compared.
When comparing subcells, arrays will be expanded into individual
instances before comparison, avoiding false differences between
arrayed and unarrayed equivalents. The returned handles (if any)
contain all differences without limit. Properties are ignored.
The arguments are:
- cx_handle1
Handle to an archive context.
- cx_handle2
Handle to an archive context, or zero. If zero, the cell should
exist in memory.
- cellname
Name of cell to compare.
- layer_list
String of space-separated layer names, or zero which implies all
layers.
- obj_types
String consisting of the layers c,b,p,w,l, which determines
objects to consider (subcells, boxes, polygons, wires, and labels), or
zero. If zero, ``cbpw'' is the default, i.e., labels are
ignored. If the geometric argument is nonzero, all but 'c' will
be ignored, and boxes, polygons, and wires will be compared.
- skip_layers
If this boolean value is nonzero and a layer_list was given,
the layers in the list will be skipped. Otherwise, only the layers in
the list will be compared (all layers if layer_list is passed
zero).
- geometric
If this boolean value is nonzero, a geometric comparison will be
performed, otherwise objects are compared directly.
- array
This is a two-element or larger array, or zero. If an array is
passed, upon return the elements are handles to lists of box, polygon,
and wire object copies (labels and subcells are not returned): array[0] contains a list of objects in handle1 and not in handle2,
and array[1] contains objects in handle2 and not in handle1.
The H function must be used on the array elements to access the
handles. If the argument is passed zero, no object lists are
returned.
The scalar return can take the following values:
-1 |
An error occurred, with a message possibly available
from the GetError function. |
0 |
Successful comparison, no differences found. |
1 |
Successful comparson, differences found. |
2 |
The cell was not found in handle1. |
3 |
The cell was not found in handle2. |
4 |
The cell was not found in either handle. |
- (string) CxFileName(cx_handle)
This function returns a string containing the full path name of the
file associated with the context handle argument. A null string is
returned on error.
- (string) CxFileType(cx_handle)
This function returns a string containing the file format of the
archive file associated with the context handle passed. A null string
is returned on error. Other possible returns are ``CIF'',
``GDSII'', ``CGX'', and ``OASIS''.
- (stringlist_handle) CxTopCells(cx_handle)
This function returns a handle to a list of strings that contain the
top-level cell names in the hierarchy associated with the context
passed (physical cells only). The top-level cells are those not used
as a subcell by another cell in the context. A scalar zero is
returned on error.
- (stringlist_handle) CxLayers(cx_handle)
This function returns a handle to a list of strings that contain the
names of layers used in the context passed as the argument (physical
cells only). For file formats that use a layer/datatype, the names
are four-byte hex integers, where the left two bytes are the
zero-padded hex value of the layer number, and the right two bytes are
the zero-padded value of the datatype number. Each unique combination
or layer name is listed. A scalar zero is returned on error.
- (string) CxEstSkelSize(cx_handle)
This return value is a string containing a floating-point number,
which is an estimate in megabytes of the memory required to hold the
context in a skeleton representation in the regular database. This
takes into account the pruning implicit when CxSetArea is
applied. A null string is returned on error.
- (int) CxCellBB(cx_handle, cellname, array)
This returns the bounding box of the named cell. The cellname
is a string giving the name of a physical cell found in the context.
If cellname is passed 0, the first top-level cell found in the
archive file will be used. The values are returned in the array, which must have size 4 or larger. the order is l,b,r,t. One
is returned on success, zero otherwise. The cell bounding boxes for
geometry are computed as the file is read, so that if the NoReadLabels variable is set during the read, i.e., when GetArchiveContext is called, text labels will not contribute to the
bounding box computation.
- (int) CxSetArea(cx_handle, cellname, l,
b, r, t, perm)
This will configure the context so that only cells and instances that
overlap the rectangle given by the l,b,r,t arguments, when reflected to the coordinates of cellname,
will be active. The top-level cell is taken as cellname. If
cellname is passed 0, the first top-level cell found in the
archive file will be used. Thus, the hierarchy if effectively
``pruned'', leaving only elements required to represent the given area
in cellname.
The coordinates are given in microns. One is returned on success,
zero otherwise.
- (int) CxClearArea(cx_handle)
This will undo the configuration applied by SetArea, if the perm flag was not set. This function will have no effect otherwise.
One is returned on success, zero if an error occurs.
- (int) CxSetSkipFlag(cx_handle, cellname,
skip)
This will set/unset the skip flag in the context for the cell named in
cellname (physical only). If cellname is passed 0, the
first top-level cell found in the archive file will be used. With the
skip flag set, the cell is ignored in the context, i.e., the cell and
its instances will not be included in output or when reading into
memory. The last argument is a boolean value: 0 to unset the skip
flag, nonzero to set it. The return value is 1 if a flag was altered,
0 otherwise.
- (int) CxSetSkipEmpties(cx_handle, cellname
[, left, bottom, right, top ])
This will set the skip flags of all physical cells in the hierarchy
under cellname that contain no readable geometry or non-empty
subcells. If cellname is passed 0, the first top-level cell
found in the archive file will be used. If the optional box
coordinates are given (in microns), the skip flags will be set for
cells that have no geometry or subcells containing geometry that
would appear in the given area in the top-level cell. This is useful
when windowing is to be employed with clipping but not flattening,
which can generate empty cells that otherwise wouldn't be caught.
This will examine the source file to determine cell content, and
takes into account the current layer filtering. This can be called
before writing (though CxWrite has its own flag for this
purpose) or opening the hierarchy to remove empty cells. The return
value is 1 on success, 0 otherwise.
- (int) CxClearSkipFlags(cx_handle)
This will reset the skip flags for all cells in the context. The
return value is 1 on success, 0 otherwise.
- (int) CxEdit(cx_handle, cellname)
This will read the given cell and its descendents into memory and open
the cell for editing, similar to the Edit function. The return
value takes the same values as the Edit function return.
The cellname, if nonzero, must be the name of a cell in the
context. This is the cell name after any aliasing that was in force
when the context was created. If cellname is passed 0, the
first top-level cell found in the archive file will be used.
If the context has been configured for area with CxSetArea for
the cell, only the cells and instances needed to display the
configuration area will be brought into memory. Cells will contain
geometry that is outside of the configuration area, but not contain
instances that are entirely outside of the configuration area.
- (int) CxSetupSkeleton(cx_handle, cellname, l,
b, r, t)
This function will create a skeleton hierarchy in memory from the
context, using the area configuration if applied. If no area
configuration was applied, the entire hierarchy under cellname
is created. If cellname is passed 0, the first top-level cell
found in the archive file will be used.
The cell created for cellname becomes the current cell, and the
skeleton mode functions can be used in the normal way. The original
archive file must remain available and not be modified, as cells are
accessed through offsets into the file saved in the context when
geometry is read.
The l, b, r, t parameters set the
bounding box that will be applied when reading geometry (i.e., an
implicit call to SkelSetDataWin with these parameters). These
should be the same as or a sub-rectangle of the bounding box passed to
CxSetArea, in microns, if an area configuration was applied.
Otherwise, the rectangle should intersect with the bounding box of
cellname.
The return value has the same interpretation as the return from the
Edit command, with 1 indicating success and 0 failure but other
values may appear in strange cases.
- (int) CxWrite(cx_handle, scale, cellname,
array, clip, all, flatten,
no_empties, outfile)
This will write the cell named in the cellname string to the
output file given in outfile. If cellname is passed 0,
the first top-level cell found in the archive file will be used. If
the boolean argument all is nonzero, the hierarchy under the
cell is written, otherwise only the named cell is written. If the
outfile is null or empty, native cell files will be created in
the current directory. If the outfile is the name of an
existing directory, native cell files will be created in that
directory. Otherwise, the extension of the outfile determines
the file type:
CGX |
.cgx |
CIF |
.cif |
GDSII |
.gds, .str, .strm, .stream |
OASIS |
.oas |
Only these extensions are recognized, however CGX and GDSII allow
an additional .gz which will imply compression.
If the context has been configured for area with CxSetArea for
the cell, only the cells and instances needed to display the
configuration area will be written.
The scale will multiply the scale factor provided to GetArchiveContext in output.
The cellname, which can not be null or empty, must be the name
of a cell in the context. The is the cell name after any aliasing
that was in force when the context was created.
If the array argument is passed 0, no windowing will be used.
Otherwise the array should have four components which specify a
rectangle, in microns, in the coordinates of cellname. The
values are
array[0] |
X left |
array[1] |
Y bottom |
array[2] |
X right |
array[3] |
Y top |
If an array is given, only the objects and subcells needed to render
the window will be written. This window should be equal to or
contained in the window used to configure the context, if any.
If the boolean value clip is nonzero and an array is given,
objects will be clipped to the window. Otherwise no clipping is done.
If the boolean value all is nonzero, the hierarchy under cellname is written, otherwise not. If windowing is applied, this
applies only to cellname, and not subcells.
If the boolean variable flatten is nonzero, the objects in the
hierarchy under cellname will be written into cellname,
i.e., flattened. The all argument is ignored in this case.
Otherwise, no flattening is done.
If the boolean value no_empties is nonzero, empty cells and
their references will not appear in output.
The return value is 1 on success, 0 on error, or -1 if an interrupt
was received.
- (int) CxOpenFlat(cx_handle, scale, cellname,
array, clip)
This will read the cell named in the cellname string and its
subcells into memory, creating a flat cell with the same name. If a
cell named cellname already exists in memory, it will be
overwritten. If cellname is passed 0, the first top-level cell
found in the archive file will be used.
If the context has been configured for area with CxSetArea for
the cell, only the cells and instances needed to display the
configuration area will be read.
The scale will multiply the scale factor provided to GetArchiveContext.
The cellname, which can not be null or empty, must be the name
of a cell in the context. This is the cell name after any aliasing
that was in force when the context was created.
If the array argument is passed 0, no windowing will be used.
Otherwise the array should have four components which specify a
rectangle, in microns, in the coordinates of cellname. The
values are
array[0] |
X left |
array[1] |
Y bottom |
array[2] |
X right |
array[3] |
Y top |
If an array is given, only the objects and subcells needed to render
the window will be read. This window should be equal to or contained
in the window used to configure the context, if any.
If the boolean value clip is nonzero and an array is given,
objects will be clipped to the window. Otherwise no clipping is done.
Before calling CxOpenFlat, the memory use can be estimated by
calling the CxEstFlatMemoryUse function.
The return value is 1 on success, 0 on error, or -1 if an
interrupt was received.