Basic Parts of an ADS Design Kit

This section details the basic parts of an ADS design kit. ADS Design Kit Tutorial guided you step by step through building a design kit with each of the parts described in this section. As described in Understanding the ADS Design Kit File Structure, the basic parts of a design kit are those that define the components, the simulation data, as well as a simple file to identify the design kit to ADS, and the AEL files required to load the design kit.

As you build your design kit, keep in mind that if your kit includes translated models, verification of the translated models is an essential part of design kit creation and may take more time than building the kit itself. For more information on the verification process, refer to Verifying a Design Kit.

Design Kit Name

Each design kit must have a unique name and the name cannot include spaces. Since an ADS user may have multiple design kits loaded, from different sources, the design kit name should be informative. It should contain the name of the company or foundry as well as the name and/or version of the process.

The name of the design kit is only used in a couple places. It is the name of the directory that all the other subdirectories are stored under, as illustrated in Understanding the Directory Contents. The design kit name is entered into the template ads.lib file. From the ads.lib file, it becomes visible in the dialogs for end users. These dialogs are used to load and set up the design kits that are accessible in ADS. For more information on the user interface, refer to Design Kit Installation and Setup.

A design kit name may also be shown on the component palette, if a palette is provided, but this is not an automatic correlation. The palette title is set in a different location than the design kit name. A design kit may contain multiple palettes. Each palette should contain the name of the design kit in addition to whatever other information is appropriate. Palette titles can have spaces in them. The palette is the location where the user will most often see the name of the design kit because the palette is visible at all times in the schematic window. The list of default system palettes, plus the example palette from the design kit tutorial, are shown in Design Kit Tutorial Palette Name.

Design Kit Tutorial Palette Name

Components in a Design Kit

Defining a component in ADS requires entries in a number of files. Information must be provided to control the behavior of the component when used in a schematic or layout or when processed by the simulator. The component definition AEL file contains much of this information.

Components can be presented to the user in an ADS Schematic window palette or in the Component Library window or both. Symbols are required for both of these methods.

Bitmaps are only required for the component palette. Additionally, you can set your design kit components up to be loaded on demand. For kits with large numbers of components, this reduces the impact on ADS startup time.

The items that must be defined for each component in a design kit are explained in the following sections:

• Component Name

• Item Definition

• Schematic Symbol

• Component Palette vs. Component Library Window

Component Name

Component names are a unique identifier of each component loaded in ADS at any given time. The name is visible in the balloon that is displayed when you hold your cursor over a palette tile. It is also visible on the ADS schematic after you have placed your component. Eventually, the component name is passed to the simulator in the netlist.

Since the component name is a unique identifier, each component name must be completely unique in the ADS system, not just within a library. If another design kit uses the same name, the one that is loaded last will overwrite any that were loaded before it. Do not place any design files (*.dsn) into your design kit that have the same name as your component. This includes symbols, sub-circuits, and fixed artwork.

You can test a new component name by entering it in the Component History field as shown in below. The system is case-sensitive so names must be capitalized exactly as shown.

ADS Component History

If you receive the error Failed to locate the component definition after entering your new component name, this is an indication that the name is not currently being used in ADS. To ensure that your component names are completely unique, you should prefix each component name with an identifier which links it back to the design kit. For example, the name of an RFIC foundry component would include:

• The name of the foundry
• The specific foundry process
• The common device type identifier

Separate the words in your component name with an underscore to make it more readable.

Example:

<foundry>_<process>_<device type>

Another advantage of prefixing each component with a string such as the design kit name is that sometimes a design that was built with design kit components will get sent to someone who does not have that particular design kit loaded. In this case, when the design is opened, a generic message indicating that the component was not found is all that the user would see. Then, when they look at the schematic, there will be a skeletal symbol with only pins and the component name. Seeing the component name will help them determine the library that the component came from.

Using Valid ADS Characters

The legal character set for Advanced Design System names is:

Note that, other than alphanumeric and underscore characters, all other legal characters require special handling in ADS. It is highly recommended that you use only alphanumeric and underscore characters in any part of your design kit.

Reserved Words

There is also a list of reserved words in ADS which cannot be used for component names. For more information on reserved words in ADS, refer to ADS Reserved Words - Alphabetical List.

Item Definition

All components that exist in ADS are added by calling an AEL function called create_item(). Each component can have a number of parameters, which are added to the system by calls to the function create_parm(). The combination of these calls is referred to as the item definition. A user interface is provided to set up some of this information, but it also usually requires some additional manual editing. The tutorial gave an example of this process.

In addition to parameters and their default values, the item definition in ADS contains information about a component that is necessary for display on the schematic. There is also information included that is needed for simulation. The following section describes the syntax and the arguments of the create_item() function that are important for design kits.

The syntax for the create_item() command is shown here. The square brackets indicate optional parameters, but are not entered in the actual function call.

create_item(name, desc, prefix, attrib, priority, iconName, dialogCode,
dialogData, netlistFormat, netlistData, displayFormat,
symbolName,artworkType, artworkData [, extraAttribute, cbList,
parameterN]);

An example similar to that in the tutorial is repeated here for reference. The callback and create_parm() information is incomplete but is sufficient for demonstration purposes. The parameter descriptions are included in The create_item() Parameter Descriptions.

create_item("mykit_npn", "MYKIT Nonlinear Bipolar Transistor", "BJT", NULL,
NULL, NULL, standard_dialog, CmpModelNetlistFmt,
ComponentAnnotFmt, SYM_mykit_npn, no_artwork, NULL,
ITEM_PRIMITIVE_EX, list(callback1, callback2, etc),
create_parm("parm1",...), create_parm("parm2",...));

The create_item() Parameter Descriptions

How to Use Attribute Codes

There are two arguments in the create_item() function that contain attribute codes. In the syntax example above, one is called attrib and the other is called extraAttribute. Each attribute is actually a combination of a number of individual attribute codes, added together. To determine the value to set in the call to create_item(), add the numerical equivalent of all desired codes. An example is shown below with the few codes that might be used in design kit components.

For a more complete list of the commonly used attribute codes, use the codes and values from create_item() Attribute Choices to set the attrib argument. Use create_item() Extra Attribute Choices to set the extraAttribute argument. These are stored in separate arguments because the size of the number that can be stored in memory is limited and would be exceeded if the codes from both attributes were stored in one location. Do not mix values from the different tables.

Attribute Code Examples

For the attrib argument, the attribute code most applicable to design kit components is the code called ITEM_UNIQUE. This is used for the process include component and it means that only one instance of this component can be placed in a schematic page.

From create_item() Attribute Choices, the numerical value of that code is 8. Therefore, the create_item() function call for a process include component will have the value 8 for the attrib argument. For better documented code, you might choose to use the more descriptive code and set the value to ITEM_UNIQUE, from the first column in create_item() Attribute Choices.

All other design kit components should not need any of the attributes from create_item() Attribute Choices, so the value 0 or NULL or ITEM_NORMAL should be set. ITEM_NORMAL is not shown in the AEL documentation.

For the extraAttribute argument, set ITEM_PRIMITIVE_EX to indicate to the simulator that the component is a native component in the simulator. ITEM_CKT_MODEL_EX would be set for a user-compiled model for Analog/RF. ITEM_SP_MODEL_EX indicates a user-compiled model for DSP. Other common codes for the extraAttribute argument are given in create_item() Extra Attribute Choices.

Parameter Definition

This section describes the syntax and arguments for the create_parm() function, which is used as an argument in the create_item() function, described above. More information is included in Component Definition Functions in the AEL documentation.

The syntax for the create_parm() command is shown here. The square brackets indicate optional parameters, but are not entered in the actual function call.

create_parm(name, desc, attrib, formSet, unitCode, defaultValue [,cbList]);

An example similar to that in the tutorial is repeated here for reference. The callback information is incomplete but is sufficient for demonstration purposes. The parameter descriptions are included in The create_parm() Parameter Descriptions.

create_parm("Model", "Model Instance Name", 0, "StdFileFormSet", -1,
prm("StdForm", "BJTM1"),
list(callback1, callback2, etc));

The create_parm() Parameter Descriptions

Saving the Item Definition

As you learned in the Adding Demand Loaded Components, the AEL file that contains the item definitions must follow a certain format. The only restriction is that the create_item() call be the last function for each component. The other code that is in the file will be global variables, forms and formsets, and netlist and parameter callbacks. It is recommended that you always present the code in this order. The file mykit_process.ael, which is shown in the Design Kits for RFIC Dynamic Link, is a good example of this format and can be used as a template for development of item definition files. You also learned in the tutorial that item definitions can be combined in one file or be kept separate with one component per file. If you combine the components in one file, make sure that each section looks like the template file and that the create_item() function call is always the last piece of code per component in case you choose to create an IDF file for demand-loaded libraries at some point, now or in the future.

Forms and Formsets

The file mykit_process.ael in Example Process Component with Forms and Formsets introduces an important topic not covered in the tutorial. It is the use of forms and formsets. This is a method of making user-defined lists that can be presented to the user when they are placing a component on the schematic. The syntax for the function calls to create a formset and a constant form are both very simple. Look at the code sample in Example Process Component with Forms and Formsets and the syntax listed below. More information is available in Component Definition Functions in AEL. Other types of forms are available as well.

create_constant_form(name,desc,attribute,netlistFormat,displayFormat);
where:

name is a string representing the form name.
desc is a description of the form.
attribute is an integer, usually 0 for this type of form.
netlistFormat is the format string to netlist the parameter value as. This is blank in the example in Setting Up Design Kit Software and Menus because there is a netlist callback that sets the value. If there were no netlist callback, the string might be similar to the displayFormat string which shows up on schematic.
displayFormat is the format string to display in a schematic.

create_form_set(name,formName1,formName2,....formNameN);
where:

name is the name of the form set. This is used by the create_parm() function.
formName is one or more form names, such as the "name" parameter in the create_constant_form() function above.

Note that forms and formsets require the same treatment as all other AEL functions and variables - their names must be unique in the whole ADS environment, including all loaded design kits. So use the same method prescribed for all names in a design kit - prefix them with the design kit, company and/or process name.

Schematic Symbol

When a component is selected from the Component Palette List or the Component Library window, an instance of the component is attached to the cursor and an outline of the component symbol is displayed as the mouse is dragged across the screen. When the mouse is clicked in the schematic window, an instance of the symbol is drawn on the screen. As a design kit creator, you must create the symbol graphics that are displayed on the schematic.

Typical ADS symbols are one schematic inch wide from the left most pin to the right most pin. The traditional location for pin 1 is on the left. If there is more than one pin on the left side of the symbol, the upper most pin is usually pin 1. Pin 1 is also typically defined as the origin, which is the point where the cursor is when then symbol is dragged across the schematic page.

There are several ways to create a symbol for your design kit.

• Drawing a New Symbol describes one way of creating a symbol using the ADS Symbol Editor.

• Copying an Existing Symbol is another way to create and modify a built-in symbol or a symbol from another design kit or library.

• A third option is to use the IFF export tool from another system such as Cadence DFII and then import the symbol into Advanced Design System. For more information on IFF export and import, refer to the IFF translation documentation for the product you are interested in. The available documentation is
  • "Translating Cadence Schematics"
  • "Translating Mentor Graphics Schematics and Layouts"
  • "Translating Mentor Graphics Libraries"

    Note

    It is possible that you will decide to use unmodified built-in ADS symbols in your design kit. In this case, the symbols do not need to be copied to your design kit circuit/symbols directory. You can simply reference the symbol by name in your create_item() command. No definition is needed.

Drawing a New Symbol

To draw a new symbol for your design kit:

1. Choose File > Open Project to open a project with a new schematic window. For more information on ADS projects, refer to Managing Projects and Designs.
2. Access the ADS Symbol Editor by choosing View > Create/Edit Schematic Symbol. The Symbol Generator dialog box appears.
   
3. Close the Symbol Generator dialog and draw the symbol by hand.
4. See also, Setting the Design Type for Symbols.

For more information on creating symbols in ADS, refer to Drawing a Custom Symbol and/or ADS Schematic Symbol & Bitmap Creation.

Copying an Existing Symbol

To copy an existing symbol for your design kit,

1. Open a schematic window.
2. Choose File > Open Design to open the appropriate symbol file. You will find built-in ADS symbols in the directory $HPEESOF_DIR/de/symbols and $HPEESOF_DIR/circuit/symbols. $HPEESOF_DIR is the installation directory for ADS. To copy symbol files from another design kit, browse to the circuit/symbols directory of the design kit. Symbols are stored as .dsn files, also known as design files. Once you have opened the design file, re-save it in the current project directory as the component name.
3. See also, Setting the Design Type for Symbols.

Detailed steps on this process are provided in the tutorial in ADS Design Kit Tutorial.

For more information on creating symbols in ADS, refer to Drawing a Custom Symbol and/or ADS Schematic Symbol & Bitmap Creation.

Setting the Design Type for Symbols

Symbols are stored as .dsn files, also known as design files. Ensure that the design type is set correctly in your design file (i.e. design type must be set to -1 for symbols). For example, a typical second line of a SYM_*.dsn file would appear similar to:

10 -1 "SYM_abc" 2 954523902 0 0 0 0

Where "-1" indicates the symbol design type. Note that the number after the line starting with 10 specifies the design type. For example, a "1" would specify a design type of AnalogRF, whereas an "11" would indicate sigProc/Ptolemy.

Component Palette vs. Component Library Window

You must decide if your design kit components will be accessed from the component palette, the Component Library window, or both. You must also decide if your components will be loaded only when used (demand-loaded), to save time at ADS startup, or if the parts will be loaded into memory when the library is loaded.

For a design kit with a limited number of components, selecting a component from the palette is quick because the palette is a permanent part of the schematic window and there are pictures that enable quick identification of the components.

Finding a component on a palette is not efficient if the design kit has a large number of components. In this case, use the Component Library window. The disadvantage is that the Component Library is a separate window from the schematic page. A distinct advantage is that the Component Library window has search capabilities. When defined with control files, the Component Library window has other advantages, listed below.

There are two methods for defining components in the Component Library window. One is a simple AEL function call, library_group(), that is usually used in conjunction with the command to create the palette, dk_define_palette_group(), or when the component is created, create_item(). The other method uses Component Library window control and record files to give more functionality, including the ability to group components in sub-libraries.

Using Component Library window control and record files is required if components are to be demand-loaded. A benefit of demand-loaded libraries is that you can ship the platform independent binary item definition file (*.idf) with your design kit and avoid shipping the .ael files, thus protecting your code from being modified by the end user. Even if you do not use the .idf file, you can still remove .ael files before shipping your design kit, leaving only the platform-independent compiled versions of those files (.atf files). This is explained more in Packaging for Distribution.

The benefits of using the Component Library window with the control and record files are:

• It allows for a multiple-tier library presentation (library/sub-library/sub-library etc.).
• It allows access to additional fields in the Component Library window.
• It allows for selected components to appear in the Component Library window when a schematic is open, but not when a layout is open, or vice-versa.
• It is a necessary condition for using demand-loaded components.
  The functions mentioned above are defined in the sections below, and the ADS Design Kit Tutorial provides specific examples of each method.

Component Palette

To define a component palette, use a function call to the ADS design kit infrastructure function dk_define_palette_group() in a file called palette.ael. This file should be saved in the de/ael directory of your design kit directory structure.

Note that the syntax for the function call dk_define_palette_group() is exactly the same as the function de_define_palette_group().

dk_define_palette_group(winType, dsnType, groupName, groupLabel, position, item1name, item1label, item1bitmap name[, item2name, item2label, item2bitmap name, ...] );

Has the same syntax as:

de_define_palette_group(winType, dsnType, groupName, groupLabel, position, item1name, item1label, item1bitmap name[, item2name, item2label, item2bitmap name, ...] );

The square brackets indicate that the number of items in the palette is variable. The group of three parameters, item1name, item1label, and item1bitmap, are a set and all three have to be defined for each component in the palette. Do not include the bracket in your AEL code. For more information on function syntax and usage, refer to Component Definition Functions in AEL.

The following values are used for this application:
winType = SCHEM_WIN
dsnType = "analogRF_net" or "sigproc_net"
groupName = name of palette
groupLabel = descriptive label for palette
position = position is an integer that indicates where the new palette is added in the list of palettes:
-1 -alphabetically sort the list of palettes after adding the new palette.
-2 - append the new palette at the end.
>0 - insert the new palette in the specified position in the list of palettes.
item<n>name = name of component as registered in create_item() call
item<n>label = description of component
item<n>bitmap = path to bitmap for the palette button.

Component Palette Management

The dk_define_palette_group()function was added in ADS2003A to keep track of the specific palettes that are installed by a design kit. If a design kit is disabled, the palettes for that design kit are disabled accordingly. The de_define_palette_group() function was used in previous versions of ADS; however, this function does not handle palette management. Therefore, the dk_define_palette_group() function is the recommended component palette group function for ADS design kits.
If you are not sure if your design kit will be used with an older version of ADS, the example code below shows one method of using dk_define_palette_group() while ensuring that your design kit will still be compatible with older versions of ADS.

Example

// if dk_define_palette_group() is defined, use that function,
// else, use de_define_palette_group ()
if(list_undefined("dk_define_palette_group();") == NULL)
{
// dk_define_palette_group() has been defined,
// ADS2003A or later use this function call instead.
dk_define_palette_group(SCHEM_WIN, "analogRF_net",
"MYKIT Components",
"MYKIT Components", 0,
"mykit_npn", "MYKIT NPN Bipolar Transistor",
strcat(MYKIT_BITMAP_DIR,"mykit_npn"),
"mykit_res", "MYKIT Resistor with SDD",
strcat(MYKIT_BITMAP_DIR,"mykit_res"),
"mykit_include", "MYKIT Netlist Include",
strcat(MYKIT_BITMAP_DIR,"mykit_include")
);
}
else
{
// dk_define_palette_group() not defined yet, pre ADS-2003A
// use this function call for ADS versions prior to ADS2003A
de_define_palette_group(SCHEM_WIN, "analogRF_net",
"MYKIT Components",
"MYKIT Components", 0,
"mykit_npn", "MYKIT NPN Bipolar Transistor",
strcat(MYKIT_BITMAP_DIR,"mykit_npn"),
"mykit_res", "MYKIT Resistor with SDD",
strcat(MYKIT_BITMAP_DIR,"mykit_res"),
"mykit_include", "MYKIT Netlist Include",
strcat(MYKIT_BITMAP_DIR,"mykit_include")
);
}

Bitmaps

The bitmap file referenced in the palette definition is a file located in the circuit/bitmaps/pc or circuit/bitmaps/unix subdirectory of the design kit directory structure. The bitmap is used to make the picture icon on the palette, to enable quick selection of a component by visual identification. In addition to a picture, the bitmap can contain a few short words to identify the component and the design kit to which it belongs.

There are different ways to create a bitmap. Windows programs like Paint can be used. The ADS DesignGuide Developer Studio can also be used and is recommended as it gives access to sample bitmaps and is designed to create bitmaps specifically for use in ADS. The DesignGuide Developer Studio is shipped with ADS and can be used without a license; however, it is not installed by default.

Bitmaps should be created as 32x32 pixels and saved as 16 color bitmaps. If you create your bitmaps on the PC, a unix version needs to be generated from the pc file. The program $HPEESOF_DIR/adsptolemy/bin.win32/bmptoxpm.exe can be used for this purpose. The free-ware program XnView can be used as well to save the X windows (unix) version of a bmp file. If you use the DesignGuide Developer Studio, you can save both formats directly from the bitmap editor.

Note that the standard way to store bitmaps for an ADS design kit is to give the unix and PC bitmaps identical names and store them in subdirectories called unix and pc, under the circuit/bitmaps directory of the design kit. The .bmp extension can be used for both. The DesignGuide Developer Studio bitmap tool has Save As commands for both unix and pc. More information is included in ADS Design Kit Tutorial.

Component Library Window

Design kit components can be entered into the Component Library window in one of two ways. The simplest way is with a function call to library_group(). An example of this is given in the tutorial. It is a simple list of the components as defined in the item definition, preceded by two arguments that identify the name and description of the library. The syntax from AEL is:

library_group(name, label, item1, item2, ..., itemN);

If the component palette has been defined as above in palette.ael, this command can be added to that file, or it can be added to the boot.ael file defined in Creating the boot.ael File.

The other way to define a library for the Component Library window is by setting up control and record files in the circuit/records subdirectory of your design kit as defined in the next section. This method provides the functionality listed in the section Component Palette vs. Component Library Window. All library control files (.ctl) in the <design_kit_name> /circuit/records directory will be loaded automatically when the library is activated. Record files will be called by the control file when they are required. The control file defines the libraries and the record files list the components in each library.

The Control File

The control file creates the multi-tier presentation (library/sub-library) in the Component Library window. The control file uses the Extensible Markup Language (XML) format. The syntax of the control file is shown below. All words and characters shown are required tokens (except the dots). Dots indicate where the information is filled in for each library. The indentation shown below is not required, but it is useful to ensure that XML key words are properly nested.

<?xml version="1.0" ?>
 	<LIBRARIES>
 	<LIBRARY>
 	<NAME>...</NAME>
 	<CATEGORY>DL</CATEGORY>
 	<SUBLIBRARY>
 	<NAME>...</NAME>
 	<RECORD_FILES>...</RECORD_FILES>
 	</SUBLIBRARY>
 	<SUBLIBRARY>
 	<NAME>...</NAME>
 	<RECORD_FILES>...</RECORD_FILES>
 	</SUBLIBRARY>
 	<SUBLIBRARY>
 	<NAME>...</NAME>
 	<RECORD_FILES>...</RECORD_FILES>
 	</SUBLIBRARY>
 	<SUBLIBRARY>
 	<NAME>...</NAME>
 	<RECORD_FILES>...</RECORD_FILES>
 	</SUBLIBRARY>
 	</LIBRARY>
 	</LIBRARIES>

Valid library categories for the <CATEGORY></CATEGORY> argument include DL (Vendor Component Device Library), CKT (Analog/RF Library), and DSP (ADS Ptolemy Library). The DL category is recommended for design kits.

Sub-libraries are optional; but if not used, then RECORD_FILES must be defined for the library. You can also put sub-libraries into sub-libraries to several levels of depth. Multiple record files can be specified on one line, separated by a space.

The following optional fields can be defined for each library or sub-library.

<URL>...</URL>

Enter any appropriate web address where the user can find information on the library or component.

<AVAILABILITY>...</AVAILABILITY>

Valid settings are Available, Obsolete, and Not Available.

<PLACEMENT>...</PLACEMENT>

The PLACEMENT tag indicates where the component can be used. Valid settings are Both, Layout, Noschematic, and Nolayout. This line is optional and the default value is Both.

The Record File

A record file lists all of the components in a sub-library. Each record file must have the extension .rec. The format for the record file is similar to that of the control file.

<?xml version="1.0" ?>
 	<COMPONENTS>
 	<COMPONENT>
 	<NAME>...</NAME>
 	<DESCRIPTION>...</DESCRIPTION>
 	<VENDOR>...</VENDOR>
 	<LIBRARY>...</LIBRARY>
 	<PLACEMENT>...</PLACEMENT>
 	<AVAILABILITY>...</AVAILABILITY>
 	<URL>...</URL>
 	</COMPONENT>
 	</COMPONENTS>

Multiple component sections can be defined between the beginning and ending COMPONENTS tags.

Multiple record files can be specified on one line, separated by a space.

The PLACEMENT tag indicates where the component can be used. Valid settings are Both, Layout, Noschematic, and Nolayout. This line is optional and the default value is Both.

The following optional fields can be defined for each library or sub library.

<URL>...</URL>

Enter any appropriate web address where the user can find information on the library or component.

<AVAILABILITY>...</AVAILABILITY>

Valid settings are Available, Obsolete and Not Available.

For more information on setting up Component Library window files for a design kit, refer to Adding Components to the Component Library Window.

Example

 <?xml version="1.0" ?>
 	<COMPONENTS>
 	<COMPONENT>
 	<NAME>Diode23</NAME>
 	<VOLTAGE>15</VOLTAGE>
 	...
 	</COMPONENT>
 	</COMPONENTS>

The Library Definition File

This file is optional and is new for ADS 2008 Update 2. With this file new columns of information can be added to a library and shown in the Component Library window.

<?xml version="1.0" ?>
 	<LIBRARYDEFINITION>
 	<COLUMN>
 	<NAME>...</NAME>
 	<TAG>...</TAG>
 	</COLUMN>
 	<COLUMN>
 	<NAME>...</NAME>
 	<TAG>...</TAG>
 	</COLUMN>
 	</LIBRARYDEFINITION>

Enter the name of a new column. This will be the name shown at the top of the column in the Component Library window. If another library is using the same name that you plan to use, use the same name as the other library. This will avoid having separate columns added for each library.

<NAME>...</NAME>

Enter the tag for the new column. The new tag can then be used as an XML tag in a record file between the COMPONENT tags.

<TAG>...</TAG>

When naming the library definition file, ensure that you include .lbd as the suffix. Store the library definition file in the same directory that the control and record files.

Example

<?xml version="1.0" ?>
 	<LIBRARYDEFINITION>
 	<COLUMN>
 	<NAME>Voltage</NAME>
 	<TAG>VOLTAGE</TAG>
 	</COLUMN>
 	</LIBRARYDEFINITION>

Library Compatibility

Several new feature were added to the Component Library window configuration files in ADS 2008 Update 2. These features are:

• Using multiple levels of hierarchy with SUBLIBRARY tags
• Adding new columns using the Library Definition File and Record Files.
• Using the LIBRARY and SUBLIBRARY tags interchangeably

When using ADS 2008 Update 2, these features are available with libraries created with prior ADS versions. To use the ADS 2008 Update 2 Component Library window features, create both a <name>.ctl and a <name>.ctl2 control file. The <name>.ctl file will be found by older versions of ADS. It should not contain any of the new features and it should not reference any *.rec files with new columns of information. Newer versions of ADS will check for the existence of a <NAME>.ctl2 file when any <NAME>.ctl file is processed. The .ctl2 file will be used instead of the .ctl file. The ctl2 file can contain the new features and reference record files with added columns of information.

Demand Loaded Components

As described above, ADS startup time can be reduced if components in a very large library are not loaded until they are needed. This is called demand-loading. To accomplish this, all the ael functions related to the component are stored in an Item Definition File (.idf extension). This file is stored in the same directory as the control and records files, the circuit/records subdirectory of the design kit directory.

The .idf file is created by a utility program that is shipped with ADS and is stored in the bin directory under $HPEESOF_DIR, which is the installation directory of ADS. $HPEESOF_DIR/bin must be in your path to use this utility, but it should already be in your path if you are running ADS.

Also, environment variables must be configured to load shared libraries specific to your computing platform. The simplest way to do this is to source the utility bootscript.sh located in $HPEESOF_DIR/bin as shown in Sourcing the bootscript.sh File. Note that . bootscript.sh only works if you use ksh (or sh). If you use csh then the easiest way is to first switch to ksh then source the bootscript file.

Sourcing the bootscript.sh File

The above assumes you have $HPEESOF_DIR/bin in your PATH.

Alternatively, you can manually add the environment variables as described in Setting Environment Variables.

The syntax for running the program is

hpedlibgen -list <comp list file> -out <.idf file>

where <comp list file> is a simple text file listing each AEL file to be compiled. Each AEL file name is listed, one per line.

The format of the AEL files that are included is important. Each component can consist of a create_item() function call, as well as parameter or netlist callbacks and other AEL functions. For this process, the create_item() call has to be the last AEL function call for that component. In other words, the callbacks and all other associated functions must come before the create_item() function. Since each block of functions will only be loaded into ADS as needed, any common code such as a reusable utility function, which is used by more than one component, must be stored in an AEL file that is not compiled into the .idf file.

Adding Demand Loaded Components includes an example of creating the .idf file.

Model Files

Model files are one way to include simulation data in a design kit. Refer to Understanding the ADS Design Kit File Structure to determine what form your simulation data will be in. Other methods for including simulation data are discussed in Additional Parts for ADS Design Kits. The ADS Design Kit Tutorial includes an example of using a model file, the most common method for RFIC foundry kits.

Model files are typically translated from Hspice or Spectre formats. The ADS SPICE or Spectre Netlist Translator can be used to perform these translations. After translation, the ADS Model Verification Toolkit can be used to set up a suite of verification tests, where the simulation results from both simulators are compared and plotted against each other.

In the design kit structure, model files are stored in the circuit/models directory. These model files contain process variables and model cards or subcircuit models in netlist format which are referenced by the components in the schematic and need to be available to the simulator.

To give the simulator access to these model files, a netlist include component or a custom process component is placed in the schematic. The section on Adding a Netlist Include Component included an example of creating this type of component. When this component is encountered during netlisting, a #include statement is written into the netlist.

The #include statement is called a pre-processor statement. When the simulator pre-processor reads the #include statement, it reads the referenced netlist file and loads the process variables and models which are in the netlist file. Netlist Include and custom process components as well as pre-processor statements are discussed in depth in the following sections.

Another pre-processor statement commonly used in model files is the #define statement, and the corresponding #ifdef and #endif statements. These are used to define corner cases for process variations. Corner cases may also be referred to as sections. In a model file, a section is started with a #ifdef statement and ended by a matching #endif statement. A model file or set of model files will include a number of sections with different process variables and model parameters. To enable a section, a netlist must contain a #define statement before the #include statement. These pre-processor statements are also covered in the next section.

If the model files also include verilog-A files, these verilog-A files should be moved to the veriloga directory in the main design kit directory. 

Netlist Include or Process Component

As mentioned above, the best way to connect the model to the netlisted schematic parts is through the use of a Process or Include component placed on the schematic. This component does not have any connectivity information but can be used to specify information such as corner cases, as well as the name of the model file to be used for the simulation. A netlist callback on this component will generate a #include statement in the output netlist. A netlist callback is an AEL function that is executed during netlisting, the process of traversing a schematic and outputting a file for the simulator. Netlist callbacks are addressed in Netlist Callbacks.

Starting in ADS 2002, the Netlist Include component is available from the Data Items palette. This component is mentioned here to give you an introduction into how the include components work. You can use this while testing your model files, but for your final design kit, it is recommended that you create a custom component to assist your users in attaching the proper file. This was demonstrated in the tutorial in Adding a Netlist Include Component.

To use the NetlistInclude component, click the component bitmap in the Data Items palette and place it on the schematic. Alternatively, you can just type NetlistInclude in the component history field on the schematic toolbar. Double-click the component in the schematic to display the dialog box. The dialog that is used to enter the parameters for the component is shown in Netlist File Include Dialog.

Netlist File Include Dialog

The NetlistInclude component as placed in a schematic is shown in Netlist Include Component.

Netlist Include Component

For this application, only one parameter on the component needs to be filled out. This is the IncludeFiles parameter. In the NetlistInclude component dialog, select this parameter with the cursor. On the right hand side of the dialog is a browser button. To demonstrate how this works, use this browser to navigate to the mykit_models.net file that you created in the tutorial. If you did not complete that part of the tutorial, the file can be found in your ADS installation at $HPEESOF_DIR/examples/DesignKit/bjt_dc_prj/design_kit. If you cannot find this path, it is ok for this example to create an empty file called mykit_models.net.

When you have browsed to a model file and selected it, note that the IncludePath field is automatically filled in for you. You can also manually type in a path or add more paths to the existing one. Each directory can be listed in the same field, separated by space.

Sometimes more than one model file will be included in a design kit. To add more files to be included, select the IncludeFiles parameter again and click the Add button at the bottom of the Select Parameter list box. A parameter called IncludeFiles[2] will be added to the parameter list in the dialog.

The preceding section introduced the concept of a corner case. This is also sometimes called a section. A model file will typically be divided up into multiple sections, each representing a process variation that needs to be simulated. It is not possible in the simulator today to automatically simulate all corners in batch mode, so they must be specified individually on the include or process component for each simulation. In the NetlistInclude component edit parameter dialog, type the word FAST into the Section field on the right hand side of the dialog.

In order to understand the whole picture, let us now create the netlist fragment that will represent the information on this component. There is a short cut to creating the netlist without actually invoking a simulation. Open the Command Line window from the ADS Main window by selecting Tools > Command Line . In the Command field of the command line window type de_netlist(); . Enter the command using the Enter key or click the Apply button to process the command. In a text editor, open the netlist.log file in your project directory. It should look similar to the following:

#define FAST
#include "$HOME/my_design_kit/circuit/models/mykit_models.net"
#undef FAST

The commands that start with the # sign are all pre-processor commands. You can see how the information from the edit parameter dialog gets used in the netlist file. The specified corner case or section is turned on by a #define statement and the model file gets referenced by a #include statement. It is a good practice to use #undef to turn off the section after the file that uses it has been read.
A sample process component which uses forms and formsets to define corner cases by writing #define statements to the netlist is include below. Pre-processor commands will be described in more depth in the section following the sample process component.

Example Process Component with Forms and Formsets

The following AEL code can be copied and modified to create your own custom process component. Read the comments after the file for more information on how the file works.

/*---------------------------------------------------------------------+/

FILE : mykit_process.ael
COMMENTS : Component definition :
[ global variables ]
[ forms and formsets ]
[ netlist callback function ]
[ parameter callback functions ]
item definition
/+---------------------------------------------------------------------*/
/*--- global variables ------------------------------------------------*/
/*--- forms and formsets ----------------------------------------------*/
/*--- corner cases ----------------------------------------------------*/
create_constant_form("mykit_form_process_best",
"Best", 0, "", "Best");
create_constant_form("mykit_form_process_nominal",
"Nominal", 0, "", "Nominal");
create_constant_form("mykit_form_process_worst",
"Worst", 0, "", "Worst");
create_form_set("mykit_formset_process_corners",
"mykit_form_process_best",
"mykit_form_process_nominal",
"mykit_form_process_worst");
/*--- netlist callback function----------------------------------------*/
defun mykit_process_netlist_cb
(
cbP,
cbData,
instH
)
{
decl netStrg;
decl parmH, parmName, parmFormName;
/*--- #ifdef --------------------------------------------------------*/
netStrg = "#ifndef MYKIT_PROCESS\n#define MYKIT_PROCESS\n";
/*--- corner case/resistance ----------------------------------------*/
parmH = db_first_parm(instH);
// this while loop isn't necessary since there is only one parameter
// but it is shown here as an example for the user
while (parmH != NULL)
{
parmName = db_get_parm_attribute(parmH, PARM_NAME);
if (parmName == "CornerCase")
{
netStrg = strcat(netStrg, "; corners\n");
parmFormName = db_get_parm_attribute(parmH, PARM_FORM_NAME);
if (parmFormName == "mykit_form_process_best")
{
netStrg = strcat(netStrg, "#define MYKIT_BEST_SECTION\n");
}
else if (parmFormName == "mykit_form_process_worst")
{
netStrg = strcat(netStrg, "#define MYKIT_WORST_SECTION\n");
}
else
{
netStrg = strcat(netStrg, "#define MYKIT_NOMINAL_SECTION\n");
}
}
parmH = db_next_parm(parmH);
}
/*--- device models ---------------------------------------------------*/
netStrg = strcat(netStrg, "; models\n");
netStrg = strcat(netStrg, sprintf("#include '%s/circuit/models/mykit_models.n
et'\n",
MYKIT_PATH));
/*--- #ifdef --------------------------------------------------------*/
netStrg = strcat(netStrg, "#endif\n");
/*--- return to calling function ------------------------------------*/
return(netStrg);
}
/*--- item definition -------------------------------------------------*/
create_item(
"MYKIT_PROCESS", // name
"Process Include", // description label
"MYKIT_PROCESS", // prefix
"Process Include", // description label
"MYKIT_PROCESS", // prefix
ITEM_UNIQUE, // attributes
0, // priority
"MYKIT_PROCESS", // iconName
standard_dialog, // dialogName
NULL, // dialogData
ComponentNetlistFmt, // netlist format string
NULL, // netlist data
ComponentAnnotFmt, // display format string
"SYM_MYKIT_PROCESS", // symbol name
no_artwork, // artwork type
NULL, // artwork data
ITEM_PRIMITIVE_EX // extra attributes
,list(dm_create_cb(ITEM_NETLIST_CB, "mykit_process_netlist_cb",
"", TRUE)) // netlist callback
,create_parm( // parameter
"CornerCase", // name
"Corner case selection", // label
PARM_DISCRETE_VALUE, // attrib
"mykit_formset_process_corners", // formSet
UNITLESS_UNIT, // unit code
prm("mykit_form_process_nominal") // default value
)
);

The process component shown here only has one parameter, for corner case selection. The three corners are Best, Nominal and Worst. A form set and three constant forms are used to define the list of possible values that are presented to the user when the component is placed in the schematic window. The selected case is used to output the proper #define statement in the netlist. This corresponds to a section of the model file, which must be offset by a #ifdef / #endif block.

Model File Sample is the skeleton of the models file and the netlist file that are produced by the netlist callback mykit_process_netlist_cb(). Inside of the section of the model file will be process parameters and the model with the parameters corresponding to the nominal case. Similar sections will be defined in the model file for the best and worst cases.

Model File Sample

model file mykit_models.net
#ifdef MYKIT_NOMINAL_SECTION
.
.
.
#endif
netlist file from schematic
.
.
.
#define MYKIT_NOMINAL_SECTION
#include "my_design_kit/circuit/models/mykit_models.net"
.
.
.

Note that the model file in this example is hard coded as mykit_models.net. This would be changed to represent the model file or files in your design kit. The global variable MYKIT_PATH is a path variable that will have to be defined with AEL code.

The #include Pre-processor Command

To understand how pre-processor commands work, it is helpful to understand the whole simulation process. When you click the Simulate menu pick, three things happen.

• First, the schematic is traversed in a process called netlisting and a netlist file is written in the project directory. This file is saved with the name netlist.log.
• Next the simulator pre-processor reads the netlist file. If any pre-processor commands such as #include or #define are found, they are processed before the netlist is passed to the simulator. So the simulator never actually sees the #include statement. Instead, the contents of the file are read and passed to the simulator. It is especially important to understand this with respect to the #define statement and for the discussion of limitations of the pre-processor commands.
• The final step is the actual simulation of the information that is now loaded into the simulator.

The #include statement is fairly easy to understand. A path and filename are supplied and when that statement is read, the file is read and passed to the simulator. The following list of limitations should be read and understood before you continue.

• If the design kit user is attempting to do remote simulation or parallel simulation, the included files need to be present on the remote machine in the same location that they are on the local machine. This can be accomplished by NFS mounting the disks, which will avoid potential problems caused by copying files around, such as losing edits made in the remote location. If NFS mounting is not possible, a netlist callback could be written that would read the referenced file and output it directly into the netlist, instead of writing the #include line into the netlist.
• If an included file has subcircuit models or subcircuits of any type (which start with the command define ), the process or include component that generates the #include statement must be placed at the top level of the hierarchy in the design. Nested defines are not allowed, and placing this type of component into a lower level of hierarchy will result in a define statement within a subcircuit definition. If an included file contains model cards and variables only, the file can be included from any level of hierarchy.
• The name of an included file, as listed on a process or include component, cannot be a variable reference.
• No tuning, sweeping, optimization or yield can be performed on the data in the included file. Additionally, the information in an included file is not available for back annotation on a schematic or other similar functions. This is an acceptable limitation since this information can be thought of as read-only.
• The order of included files cannot be controlled if multiple separate include components are placed. The component called NetlistInclude is designed to enforce this restriction. Only one NetlistInclude component can be placed, but it takes a list of files and retains the order of the files when outputting a #include line to the netlist.

The #ifdef and #define Pre-processor Commands

As introduced above, #ifdef is used to define a corner case or section in a model file. A section can contain process variables, model cards, subcircuit definitions or a combination of these, to represent a process variation. Typical names for corner cases are FAST, NOMINAL and SLOW. A model file containing these sections would look like this:
#ifdef NOMINAL
[process variables and model parameters for the NOMINAL case would be included here]
#endif
#ifdef FAST
[the same process variables and model parameters would be included here, but with different values to simulate the FAST process variations.]
#endif
#ifdef SLOW
[the same variables and models would be included here again, but with values to simulate the SLOW process variations.]
#endif
Remember from above that the netlisted schematic that would include this model file contains the lines shown below. Note that the sample mykit_models.net file does not actually contain these sections at this time.
#define FAST
#include "C:/my_design_kit/circuit/models/mykit_models.net"
#undef FAST

The order in which all this information is processed is as follows:

1. Netlist file netlist.log is created from the schematic. The #define and #include statements are generated from the include component.
2. The simulator pre-processor reads the netlist.log file. FAST is defined and the include file mykit_models.net is read.
3. When the model file is read, the NOMINAL and SLOW sections are completely disregarded. Only the FAST section is read.

It was mentioned above that corner cases cannot be swept automatically in the simulator. This is because, based on what was shown in step #3 above, the simulator only has knowledge of one corner section at a time. The others are filtered out by the pre-processor. The user has to turn on each section individually and save the datasets for comparison.

The last concept that needs to be explained is how to use a custom process include component to make it easier for the design kit user to perform these simulations. First of all, the netlist file name can be hard-coded into a custom component. In other words, the user will not have to enter any file name. The path is known because the model file exists in the circuit/models directory of the design kit and the file name is written into the AEL code that generates the netlist. This AEL code is called a netlist callback and is explained in Netlist Callbacks.

In order to make it easier for the customer to select which corner case to simulate, the section names are presented to the user in a list, of which one at a time can be selected. To generate this list, a form set is defined in AEL code and then referenced in the item definition, also AEL code. Forms and formsets are defined in Forms and Formsets. Item definitions are covered in Item Definition. The best way to complete your understanding of these concepts is to return to the ADS Design Kit Tutorial, where two examples of custom process include components are given.

Any custom process or include component, that is required by other components in a design kit, should be listed at the top of the palette, since the user must place it in the schematic when using any other components in the design kit. In fact, it is so essential that this process component be included in a schematic, that some design kit developers will add a netlist callback to any device component that refers to a model in the netlist model file. This callback can traverse the schematic and warn the user if a process component has not been placed, or it can simply place the process component automatically.

Model Naming Limitations

As mentioned earlier, since ADS has one global name space, all components and variables in a model file must be unique, to avoid colliding with another with the same name if another file is included at the same time. This can happen, for example, when designing a multi-chip module if components from more than one design kit are used in the same design.

This requirement applies to model names, subcircuit names and global variable names. Components or variables (parameters) inside of a subcircuit are considered local and are protected automatically. <foundry> _ <process> _ <name> is the recommended naming convention for all global items in an RFIC foundry design kit. At the present time, the netlist translators do not facilitate this process, so it must be done manually or with a script run on the model file after the translation is complete.

Functions for Spectre and Hspice Compatibility

There were a number of Spectre/Hspice compatibility functions added into design kits in the 2003A release that can help you maintain your equations as is between different simulators. The simulator team at Agilent Technologies has added some of these functions into the simulator itself. If you have made your own compatibility functions, you will need to remove these functions because they will now produce a redefinition error.

The functions implemented in 2003A were:

The ads.lib Template

The ads.lib file is a design kit control file that tells Advanced Design System which design kits to load. A template of this file must be included in the design_kit subdirectory of the design kit directory structure. When a design kit is installed, a copy of the records line of the template file is made and stored outside of the design kit. The location of the file controls who has access to the design kit when ADS is started, as described below.

The format for the records line of the ads.lib template file is a single line with 4 fields, separated by vertical bars.

kitname | path to design kit | path to kit boot file | kit version

The following table provides a description for each of the fields shown.

The ads.lib Fields

To insert a comment into the template ads.lib file, begin the line with a pound sign ( # ). Comments will not be copied with the records line.

Ultimately, ads.lib files can exist in the any of the locations listed in The ads.lib File Locations. Note that these locations are referred to as levels in the ADS Design Kit user interface.

The ads.lib File Locations

With this capability, a user in a networked environment can have access to a specific design kit without exposing all engineers to it or without requiring the assistance of an administrator with root permissions to install it. Another benefit is that a site librarian can manage a set of libraries that are accessible to all engineers without any effort from the engineers. These are some typical ways that a system is configured. For more information, refer to the " Design Kit Installation and Setup " documentation.

The SITE LEVEL by default is under $HPEESOF_DIR, the installation location of ADS. On a PC network, $HPEESOF_DIR might be on each individual machine. If this is the case, an alternate location can be specified as SITE LEVEL by setting DESIGN_KIT_SITE_PATH in design_kit.cfg (see Setting Up Design Kit Software and Menus).

Another way to use this multi-layered functionality is for an end user to have a set of ads.lib files in different directories that refer to different processes. By starting ADS in the proper directory, the related design kits will be loaded for that session. An advanced CAD manager may even choose to set up a system of scripts that controls the ads.lib files for the end user to further tailor the environment on the fly for a specific manufacturing process.

Even if a design kit is listed in the system ads.lib file for access by all engineers, the engineer can still disable that configuration by telling ADS to only load ads.lib files in the local area. This can be set up by choosing the DesignKit > Setup Design Kits menu pick from the ADS Main window. The current design kit configuration can be viewed using the List ADS Design Kits dialog by choosing DesignKit > List Design Kits menu. For more information, refer to the " Design Kit Installation and Setup" documentation.

If a design kit is listed in more than one ads.lib file, those specified in the $HOME location will have precedence over those under $HPEESOF_DIR, and those specified in the startup directory will take precedence over those in the $HOME location. Additionally, each project directory may have its own ads.lib file. This file will be read when a project is opened, and any design kits specified in that file will be loaded. If a design kit by the same name is already open, it will be overwritten with the new information.

Closing a project to open a different project will not unload design kits opened in that project since design kits cannot currently be unloaded without restarting ADS.

Even though all design kits are intended to be able to coexist in ADS, there may be cases where this is not possible. Some older design kits may not comply with the standard format. Additionally, ADS has a requirement that all components have unique names in ADS, so names cannot be reused between design kits. If these types of problems are encountered, they can usually be overcome by enabling and disabling design kits as needed through the user interface or by manually editing ads.lib files and the design_kit.cfg file. Additionally, some custom AEL in older, non-standard design kits may have problems co-existing with the current built-in design kit software. Setting Up Design Kit Software and Menus includes instructions for temporarily disabling the new software for this rare case.

AEL Code for Loading a Design Kit

As mentioned in the previous section, a design kit will contain a boot file that helps the system load the design kit. The name of this file is recorded in the ads.lib file so there isn't a reserved name for the file that is searched. However, the name boot.ael is typically used in most ADS design kits today and the file resides in the de/ael subdirectory of the design kit directory structure.

A boot file can be used to load the AEL item definitions for all components in a design kit, as well as to set up the palettes. The ADS Design Kit Tutorial gives an example of this use. Additionally, the boot file may be used to define some global variables or functions specific to the design kit. These are usually for advanced functionality and specific details are not included in this document.

Including a boot file is optional. If a boot file is not specified in the ads.lib file, component AEL will still be loaded and the Component Library window will still have knowledge of the library and sub library definitions, as described earlier in this section. The program will first look for an item definition file (.idf) in the circuit/records directory. If this is found, all the item definition AEL functions will be loaded from the .idf file. If no .idf file is present, your boot.ael file must be edited to include "load" statements that cause the circuit/ael/ component definition ael files to be executed. The "load" statements may be in the boot.ael or another file that is loaded from the boot.ael file.

The about.txt File

A file named about.txt should be supplied and stored in the doc directory of the design kit structure. This is required for version tracking and will assist Agilent Technologies customer support. The file will contain information such as the design kit version and date created. Process and component information can be included, as well as source information if the models were translated from another library. Revision history, support contact information or any other details can be listed if desired.

A template for this file is shown in the table below. A future version of the design kit software may have a menu pick to give the user easy access to this information.

Design Kit about.txt Template

For more information on design kit versions, refer to Assigning a Version.

The Example Project

The quickest way to help your customers start using your design kit is to provide a sample design that they can work from. This is a simple way for them to see that a design kit is installed properly and verify that they can run a simulation. It is also a way for you to show some special features of the design kit.

To add the example project to the design kit, first create and save a small test circuit, including a process or include component if required. Then simulate the circuit and save the data display. More test circuits can also be saved if desired. When all test designs have been saved, archive the project using the File > Archive Project menu pick in the ADS Main window. Copy the archived project to the examples directory in the design kit file structure. The tutorial steps in ADS Design Kit Tutorial can also be referred to for help in building an example project and storing it with the sample design kit.