Xic Native PCells

Xic supports pcells using the native scripting language, plus Python or Tcl if the respective plug-ins are loaded. Parameterized cells are supported only in physical mode. This section will describe how to create and use native pcells in Xic. By ``native'', execution within Xic rather than through OpenAccess is meant. As will be seen, native pcells can be saved in OpenAccess, too, and they are still native.

There are several example native pcells provided in the examples directory of the Xic installation. These provide samples of the syntax used in the property strings and other aspects, with comments, and their study should facilitate understanding how to write native pcells.

A native pcell can be saved in any format supported by Xic, with certain limitations to be described. Probably, the native cell format is the most convenient. These can be easily edited with a text editor, which the advanced developer is likely to do on occasion.

A pcell can have any name that is compatible with Xic. Earlier releases of Xic required that a pcell name have a literal ``XXX'' suffix. This is no longer the case, but if the XXX is present, it will be stripped in sub-master names and replaced with a unique identifying code for the parameter set. Otherwise, the code is appended to the pcell name.

Super- and sub-master cells, and sub-master instances, differ from normal cells and instances by the presence of a few special properties. These are:

pc_name property, number 7197
This property is assigned by Xic to pcell sub-masters and their instances. It provides the name of the pcell from which the sub-master or instance was derived.

pc_params property, number 7198
This property is assigned by the user to pcells, and contains the default parameter set. It will be assigned by Xic to sub-masters and instances, and contains the parameter set that was used to create the sub-master.

The string of the pc_params property has the form

[typechar:]name[=]value[:constraint] [[,] ...]

The string consists of a series of name and value tokens. The names can not contain white space or punctuation. Ahead of the name is a type specification character if the value is not string type. In native pcells, all parameters are (for this purpose) string type, so the type specifier will never appear. However, the syntax used may be extended in future, so it is documented in the table below. All types except for string type will have a specifier. These will appear in property strings obtained from OpenAccess for non-native pcells.

b	boolean
i	integer
t	time value
f	32-bit float
d	64-bit float

Each of the name tokens is the name of a parameter that can be applied to the pcell. These will become names of variables in the script, so that these names should not be defined or used in the script text in a conflicting way.

Every name should have a value, an ``empty'' value is specified as an empty string (""). The value is separated from the name by white space, a comma, or an equal sign. The values are taken as default values for the parameters, and can be numeric values or strings. A value that contains white space, commas, or colons should be quoted. The value string can also be an executable code fragment using only parameters already defined (to the left) and constants, for example

param1=2,param2="param1 + 1"

This form, however, can not be used with constraints (see below). It can also only appear in super-master pc_params properties. the pc_params strings of sub-masters and instances must have constant values.

The quoting behavior is a bit complicated, so as to support Python and native languages. If the value is quoted with double-quote marks, the double quote marks will be stripped, and the parameter will take the enclosed characters. However, if a backslash character (` \ ') appears ahead of the first double quote, the double quote marks will be retained. In the native language, this will ensure that the parameter is string-type.

For example

myvar="123"

The parameter (variable) myvar will be assigned the value 123, causing it to become scalar-type. On the other hand

myvar= \ "123"

will assign "123" to myvar (including the quotes) thus myvar will be string-type. In general, if the value is to be taken as a string constant in the native language, a backslash should be placed ahead of the first double quote mark.

If the value is quoted with single-quote marks, the single-quote marks are retained, along with the characters between them. This is for Python support. However, if the second character is a double-quote mark, the single-quote marks will be stripped, leaving the double-quoted result. This is an alternative and somewhat deprecated way to specify a string constant in the native language.

mystring='"a string constant"'

In any case, when the parser is searching for the ending quote mark (single or double), if the mark is found but it is preceded by a backslash, both characters are taken verbatim and the search continues. Thus, the backslash can be used to hide quote marks of the same type in the string.

If the value is a constant (not an executable fragment), the value can be followed by an optional constraint specification, separated from the value by a colon (no white space is allowed around the colon). Constraints define the scceptable values for the parameter, using a syntax described in 5.2. The constraints appear only in pc_params properties of super-masters, and are not copied to pc_params properties of sub-masters and instances.

The parameter string is logically converted to a series of assignment statements which are executed before the script. For example, the parameter string

param1=1.0,name= \ "my template",param2="param1 * 2"

would map to the following logical script lines

param1 = 1.0
name = "my template"
param2 = param1 * 2

pc_script property, number 7199
This property is assigned by the user to a pcell, and appears only in the super-master. It contains the script, or a path to a script, which is executed when the pcell is instantiated.

The pc_script property text is in the form

[@LANG langtok] @READ path [@MD5 digest] | script text

The @LANG, @READ, and @MD5 tokens are literal. The langtok may be one of (case insensitive)

n[ative]	native sript, the default
p[ython]	python script
t[cl]	tcl script

The path token must appear if @READ is given. If @READ is not given, any remaining text is taken as literal executable script text.

The path is to a file containing the executable text, and should be quoted if it contains white space. If the path is not rooted, it will be searched for in a directory search path set in the PCellScriptPath variable.

When a path is given, one can also apply the @MD5 digest clause. The digest is that for the script file, and can be obtained from the !md5 command, or the Md5Digest script function, or from the command

openssl dgst -md5 filepath

on most Linux systems. If given, the script file digest must match the digest given, or the script will not be executed. This will ensure that only the ``correct'' script file is used.

Previous versions of Xic required that the script actually appear in the pc_script property string. This can still be done, and may be convenient for many pcells, particularly very simple ones. However, one may encounter a portability issue caused by string length limitations of the GDSII and CGX formats due to their maximum record length of 64KB. The native cell format, the CIF format as extended by Whiteley Research, and the OASIS format have no built-in string length limit, nor does OpenAccess.

When using separate script files, for portability it may be best to not provide a full path to the script in the pc_script property string, but give the file name only and use the search path variable. Then, the scripts can be kept in different locations at different Xic installations, and pcells will still be portable provided the PCellScriptPath is set (probably from an initialization file). The MD5 digest keying can ensure that the script file found via the search path is correct, or it will not execute.

The script, whether in a separate file or not, is basically conventional, and uses the native object creation functions to build up the geometry, presumably using the parameter values as input. The example native pcells provided with the Xic distributions in the examples directory illustrate how the script is incorporated.

One aspect of importance is the script return value, which will tell the calling program whether or not script evaluation succeeded. If evaluation fails, Xic can gracefully ``clean up'' by destroying partially completed sub-masters, and any corresponding instance placements, and alerting the user to the error.

The script should return 0 (zero) on success, which is the default if no explicit return value is specified. Any nonzero return value indicates faliure. The mechanics of setting the return value differs between the supported languages, and is described below. In every case, just before a nonzero value is returned, the AddError function should be called with a message explaining the error.

Native
The return keyword, followed by a value, will terminate the scrpt and return the value. For example, here is a snippet that checks the value of a parameter named ``top'' and fails if it is out of range:

if (top < 1 | top > 20)
AddError("Parameter top is out of range [1 - 20].")
return 1
end

Actually, if the value following return is omitted, the return value is 1, so just a bare ``return'' will signal the error condition. If the end of execution is reached and no return keyword is encountered, the value returned is 0 (success). If the script is terminated with the Halt or Exit functions, the return value is 0. If the script is halted by an internal error, the return value is -1. If the script is halted due to an interrupt signal, the return value is 1.

Python
The recommended way to induce an error exit in a Python script is to call ``sys.exit'' with a nonzero argument. The example above translated to Python will read:

if (top < 1 or top > 20):
xic.AddError("Parameter top is out of range [1 - 20].")
sys.exit(1)

Errors detected by the Python interpreter are passed back as nonzero exit returns.

Tcl
The recommended way to induce an error exit from a Tcl script is to call ``return -code error''. The example above translated to Tcl will read:

if {$top < 1 || $top > 20} {
AddError {"Parameter top is out of range [1 - 20]."}
return -code error
}

Errors detected by the Tcl interpreter are passed back as nonzero exit returns.

To summarize, a pcell is never itself instantiated. When one places an instance of a pcell, the following steps occur:

1. The pcell is read into memory as a ``super-master'' if it is not already there.

2. The user enters the parameter values.

3. The database is searched for another cell derived from the same pcell with the same parameter values, i.e., an equivalent sub-master. If one is found, a new instance is created and given pc_name and pc_params properties copied from the sub-master, and we're done.

4. Otherwise, the script is executed, in the context of a new, empty cell whose name consists of the pcell name suffixed by a unique identifier. This is the sub-master cell. It is given a pc_name property to identify the pcell, and a pc_params property to list the parameters used. The new sub-master is instantiated and the instance given the same two properties, and we're done.

Once the instance is placed, it behaves in all respects as a normal cell. It has a ``master'' derived from the pcell as a sub-master, and a unique sub-master exists for each unique parameter set. Writing the hierarchy, including the sub-masters, to an archive produces a perfectly normal file. However, by default the sub-masters are not written to output, instead they are expected to be recreated from the pcell when needed. The pcells (super-masters) are never included in the output file, since they are not directly instantiated in the hierarchy. Thus, when exporting, the pcell should be supplied separately, if needed. If sub-masters are included in the archive, then the pcell is not needed, unless further parameter changes are required. In Xic, sub-masters can be included in saved archive files when the PCellKeepSubMasters variable or equivalently the check box in the Export Control panel is set, or when the StripForExport variable or equivalent check box in the same panel is set.