next up previous contents index
Next: Conversion Up: Operating System and Input/Output Previous: Operating System and Input/Output   Contents   Index

Archive File Context

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.


next up previous contents index
Next: Conversion Up: Operating System and Input/Output Previous: Operating System and Input/Output   Contents   Index
Stephen R. Whiteley 2006-10-23