#

## gds, calma

Read GDSII input or generate GDSII output.

### Usage:

> gds [option]
> calma [option]

> > where option is one of the following:
> > Primary options:
> > help
> >   Print usage information
> > read file
> >   Read GDSII format from file file into the edit cell. If file does not have a file extension, then magic searches for a file named file, file.gds, file.gds2, or file.strm.
> > warning [option]
> >   Set warning information level. "option" may be one of the following:
> >   default
> >     The default setting is equivalent to all the other options (align, limit, redirect, and none) being disabled.
> >   align
> >     Generate warnings during a "cif see" command if the alignment of geometry is on fractional lambda. Normally, magic allows contacts to be drawn at half-lambda positions. If this violates DRC requirements for the minimum output grid, this warning setting can be used to detect such violations.
> >   limit
> >     Limit warnings to the first 100 warnings or errors only.
> >   redirect [file]
> >     Redirect all warnings to an output file named file. If file is not given, then redirection is disabled.
> >   none
> >     Do not produce any warning messages on GDS input.
> > write file
> >   Output GDSII format to "file" for the window's root cell.
> > Options for gds read:
> > datestamp [yes|no|value]
> >   When reading a GDS file, the resulting layout views in magic will be timestamped according to the declared datestamp action. If yes (the default), then the creation date timestamp from the GDS file is transferred to the layout cell. If no, then the datestamp is set to zero and will be created when the cell is saved to disk. If value, then the specified value (in UNIX format of seconds since the epoch) will be used for the layout timestamp.
> > drccheck [yes|no]
> >   If set to no, then do not mark cells read from GDS as requiring DRC checks (default yes).
> > flatglob [none|string]
> >   Flatten cells by name pattern on input. This is the more exacting version of flatten, as it allows specific cells to be flattened. Each call with an argument string adds string to the list of name patterns to be checked. A call with the option none will remove all patterns. A call with no options will return the list of string patterns that will be applied to inputs. The strings may use standard shell-type glob patterns, with * for any length string match, ? for any single character match, \ for special characters, and [] for matching character sets or ranges (introduced in version 8.3.102).
> > flatten [yes|no|number]
> >   Flatten simple cells (e.g., contacts) on input. This helps magic to use its contact-area representation of contacts, and can also avoid situations where contacts are lost or translated to "generic" types because the arrayed part of the contacts is missing one or more residue layers. The default number of shapes in an input to be considered "simple" is 10, but this can be set with the number argument. A number of zero implies flatten no, and a non-zero number implies flatten yes. Otherwise, the use of yes and no toggles the flattening behavior without affecting any value previously set by flatten number.
> > magscale [value|default]
> >   By default magic interprets the GDS magnification value of 1.0 as 1 micron for text scale. As this definition is not universal, some GDS files may read in with text at an unusual scale. The value value sets the text height in microns at a magnification of 1. Value default resets the value to the default of 1. If no option is given, then return the magnification value.
> > maskhints [yes|no|layers]
> >   When set to yes, then after reading each cell definition from the GDS file, magic will re-generate the GDS output data from its internal representation of the cell. Where the output data does not match the input data, and where the technology file defines mask hints in the cifoutput section for a GDS layer, magic will automatically generate the mask hint property for the cell such that writing GDS of the cell will produce exactly the same mask data as was in the original GDS file. Alternatively to specifying "yes", a comma-separated list layers of GDS layers to create mask hints for can be specified (default no).
> > noduplicates [yes|no]
> >   When reading a GDS file, this option forces magic to ignore cell definitions in the GDS file that are already present in the database (that is, for which a cell of the same name already exists). This can be used, for example, to pre-load an abstract view of a cell before reading a GDS file containing that cell. This option should be used with extreme caution, since there is no check as to whether the existing view is compatible with the one in the GDS file.
> > ordering [yes|no]
> >   Forces post-ordering of subcells read from a GDS file; that is, if a cell use is encountered before it is defined, magic will read through the remainder of the file until it finds the definition, read it, and then return to the original file position to continue reading. This option is always enabled when using gds flatten. Otherwise, the default behavior is ordering no to avoid lengthy searches through the GDS stream file.
> > polygon subcells [yes|no]
> >   Put non-Manhattan polygons into subcells. Default is "no". Normally this option is not needed. However, input layout that defines a number of angled wires, particularly those that are closely spaced, can cause magic to generate literally millions of internal tiles. This tends to be true in particular for corner cells in padframes for deep submicron feature sizes, where the angled corners are required to meet the DRC specification. When set to "yes", each polygon encountered in the GDS input is placed in its own uniquely-named subcell. This prevents interations with other polygons on the same plane and so reduces tile splitting.
> > readonly [yes|no]
> >   Set cell as "read-only". This has the effect of marking each cell definition (using the property method) with the start and end positions of the cell definition in the input file. In subsequent output, the cell definition will be transferred verbatim from the input to the output file. This is useful for 3rd-party standard cells or pad cells where the original GDS is trusted and it is desirable to bypass the boolean operators of magic's GDS reader and writer to prevent the layout from being altered. Note that "read-only" layout can be written to a `.mag` file, but the contents of this file are representational only. It can be useful to keep a simplified respresentation in the case of pad cells or digital standard cells, for example, by reading them using a GDS input style that defines only metal layers.
> > rescale [yes|no]
> >   Allow or disallow internal grid subdivision while reading GDS input. Default is "yes". Normally, one wants to allow rescaling to ensure that the GDS is displayed exactly as it is in the input file. Occasionally, however, the GDS input is on a very fine scale, such as nanometers, and it is preferable to snap the input to lambda boundaries rather than to subsplit the internal grid to such a fine value. The "cif limit" function may also be used to limit grid subdivision to a minimum value.
> > savepaths [yes|no]
> >   When reading paths from a GDS file, record the centerline of the path as a property in the cell. The default behavior is no. If no argument is given, then return the status of the savepaths option. The first path property is named "`path`", followed by "`path_0`" and increasing the suffix index for each individual path read.
> > unique [yes|no]
> >   When reading a GDS file, this option forces magic to rename cell definitions in the database when a cell of the same name is encountered in the GDS file. The default behavior is to overwrite the cell with the new definition. The existing cell is renamed by adding a suffix with an underscore and a number. The number is incremented until the name fails to match any known cell name in the database.
> > Options for gds write:
> > abstract [allow|disallow]
> >   Define the behavior for abstract cells (e.g., cells derived from LEF views). If allowed, then these cells will be written to GDS even if the abstraction layers (e.g., metal obstructions) have no defined GDS layers. If disallowed, the GDS file will not be written if abstract cells exist. The default behavior is disallow.
> > addendum [yes|no]
> >   Do not output vendor (readonly) cell definitions. Only the references will be output. This makes the output file an addendum to any existing vendor GDS libraries.
> > arrays [yes|no]
> >   Output arrays as individual subuses (like in CIF). Default is "no". Normally there is no reason to do this.
> > compress [value]
> >   For non-zero value, apply gzip-style compression to the output stream. Per the gzip compression algorithm, value represents a level of compression effort, and ranges from 1 to 9. When value is zero, no compression is applied and the output is standard GDS format, and the output file extension is ".gds". When value is non-zero, compression is applied, and the output file extension is ".gds.gz". With no argument, return the current compression setting. The default compression setting is zero (no compression applied; output is plain GDS).
> > contacts [yes|no]
> >   Causes contacts to be written to the GDS file as subcell arrays (experimental, introduced in version 7.3.55). This method can produce very efficient output compared to writing each contact cut square separately.
> > datestamp [yes|no|value]
> >   When writing a GDS file, each cell definition is given a header containing two date stamps, one for the creation date, and one for the modification date. By default, magic writes the cell's internal timestamp as the creation date, and sets the modification date stamp to zero. The datestamp option, if set to no, will also set the creation date stamp to zero. If set to value, then the specified stamp value will be output for the creation date. The stamp value should be an integer in the format used by the UNIX time() system call, which is the number of seconds since January 1, 1970, or equivalently the Tcl command "clock seconds". Note that very few tools make use of the GDS date stamps. But having a valid date stamp means that a GDS file cannot be written twice with the exact same contents, which has implications for repositories like git. When writing libraries, it is useful to set a date stamp tied to a version number and apply that date stamp to all files written for the library.
> > labels [yes|no]
> >   Cause labels to be output when writing GDSII. Default is "yes". Normally there is no reason not to do this.
> > library [yes|no]
> >   Do not write the top level cell into the output GDS file, but write only the subcells of the top level cell. Default is "no".
> > lower [yes|no]
> >   Allow both upper and lower case in labels. Default is "yes".
> > merge [yes|no]
> >   Concatenate connected tiles into polygons when generating output. Depending on the tile geometry, this may make the output file up to four times smaller, at the cost of speed in generating the output file. Some programs like the field equation solver HFSS won't work properly with layout broken into many tiles; other programs like Calibre will complain about acute angles when non-Manhattan geometry is broken into triangles. GDS output limits polygon boundaries to a maximum of 200 points, which limits the efficiency of the merge method. The default value if "no"; e.g., all GDS output is a direct conversion of tiles to rectangle and triangle boundary records.
> > nodatestamp [yes|no]
> >   Backwardly compatible alternative to the datestamp option. Setting nodatestamp yes is equivalent to setting datestamp no (see above).
> > undefined [allow|disallow]
> >   Define the behavior for undefined cells (e.g., cells whose layout contents could not be found). If allowed, then the calls to these cells will be written to GDS even if the cell itself is not defined in the GDS (see the addendum option, above). If disallowed, the GDS file will not be written if undefined references exist. The default behavior is disallow.

### Summary:

> The gds command reads or produces GDSII output (also known as "stream" output, or "calma" output after the name of the company that invented the format), or sets various parameters affecting the GDS input and output. In magic, the GDS read and write routines are a subset of the CIF read and write routines, and so it is important to note that certain cif command options (q.v.) also affect GDS input and output. In particular, cif istyle and cif ostyle set the input and output styles from the technology file, respectively.

> If no option is given, a CALMA GDS-II stream file is produced for the root cell, with the default name of the root cell definition and the filename extension ".gds".

> gds read will read both (gzip-)compressed and uncompressed GDS files. gds write will only write compressed files as indicated by the gds compress setting.

### Implementation Notes:

> gds is implemented as a built-in function in magic. The calma command is an alias for gds and is exactly equivalent.

### Bugs:

> - The cif command options that affect GDS input and output should really be duplicates as options of the GDS command.
> - GDS input is "interpreted" through boolean operations in the technology file definition, and so it is not guaranteed that all input will be read correctly.
> - Not all non-Manhattan geometry is read correctly.
> - The input can be fouled up if the magic grid is rescaled during input. This error can be avoided by scaling the grid prior to GDS read-in.
> - "polygon subcells" in GDS creates a duplicate image of the layout read into the subcells; this needs to be fixed.

### See Also:

> cif

Return to command index

Last updated: May 10, 2022 at 9:14am