Understanding the ADS Design Kit File Structure

This chapter describes the details of the ADS design kit file structure. The best way to learn how to build your own design kit is to follow the tutorial steps described in ADS Design Kit Tutorial. The tutorial describes how to create all the basic files and how to test the design kit as it evolves. A copy of the sample kit is provided with the ADS design kit infrastructure software. You can then use the information in Basic Parts of an ADS Design Kit and Additional Parts for ADS Design Kits to build on your understanding and customize the kit for your needs.

Overview of the File Structure

An ADS design kit is a group of files that is related to a set of ADS components, and which is self-contained for ease of transfer. The files in a design kit reside in specific subdirectories, collected under a directory that bears the name of the design kit itself. For distribution, the files are easily packaged into an archive file, in the .zip file format.

Some of the directories are required for all design kits, no matter what technology they will serve. There are also a few directories which are required depending on the technology or configuration of the design kit. Additionally, there are other directories which are completely optional and are used to provide extra functionality within the design kit.

This chapter includes an overview of all directories and the files in them, including information to help you decide which are required for your design kit. Basic Parts of an ADS Design Kit gives detailed information about the required directories and files and Additional Parts for ADS Design Kits gives detailed information about many of the optional directories and files. ADS Design Kit File Structure for Component Palette and Simulation Data in Model Files and ADS Design Kit File Structure for Library Browser Access and Simulation Data in Data Files in this chapter illustrate the structure of two simple design kits. Comprehensive Listing of Potential Directories in an ADS Design Kit is a comprehensive structure of all possible design kits directories defined at this time and Design Kit File Structure lists the types of files found in each directory.

ADS is a powerful system with capabilities for extensive customization. Design kits need to co-exist with each other and with all of the tools in the system, so they must conform to ADS standards. Agilent Technologies needs to be kept aware of the extensions that are being made for individual design kits, those that are developed by Agilent Technologies, as well as those that are not, so that as technology advances are made, this documentation and the infrastructure software can be extended to cover new areas.

The directories and files that are required for all design kits are:

circuit/ael Component definition
circuit/symbols Schematic symbols
design_kit Template ads.lib file
doc 'about.txt' information file
examples Schematic design file

Additionally, directories described below may be required to complete a minimal kit.

In ADS, components can be selected from a palette on the schematic page or from the library browser. The palette includes bitmaps so a component can be selected quickly. The library browser presents more information to the user and includes the ability to search for a component based on its characteristics. A component in a design kit can be presented in the palette or in the library browser or both. Additionally, a design kit may consist of some components that are only in the palette and some that are only in the library browser.

If design kit components will be available from a component palette, the following directories and files are required:

circuit/bitmaps Bitmap files
de/ael Boot files to enable palette

If design kit components will be available from the library browser, the following directory and files are required:

circuit/records Library browser files

If a library browser file is included in a design kit, the .ael and .atf files in the circuit/ael directory will not need to be shipped with the design kit. However, they still need to be created so they can be compiled into the browser file. This issue will be discussed further in Packaging for Distribution.

A design kit contains information needed by the simulator to perform calculations. This information may be supplied as model cards or subcircuit models in a netlist fragment. RFIC foundry kits often include SPICE model files translated from another simulator. Completion of a design kit containing these translated model files will include a verification process that involves creating circuits in both simulators and comparing the data. The ADS Design Kit Model Verification Toolkit can assist you in this task. For more information on the topic of included models, refer to Model Files.

Additional topics related to inclusion of simulation data are discussed in Adding Simulation Data to a Design Kit. For example, if the model used by the design kit is a user-compiled model, you will need to supply the custom simulator executable in the bin directory of the design kit. Additionally, schematic subcircuits may be the form that models are delivered in. A final method of including simulation data is to include the raw simulation data in the form of an mdif , s2p or citi file. For more information on the mdif , s2p or citi file types, refer to Working with Data Files.

To supply simulation data, the following files need to be provided in the specified directory:

Type of Simulation Data Directory Files
If simulation data is in the form of model cards or subcircuit models. circuit/models netlist fragments
If simulation data is in raw data form. circuit/data mdif, etc.
If a user-compiled model is included as a dynamically linked library (.dll) or shared library (.sl or .so). bin/$SIMARCH .dll (win32 and win32_64)
.sl (hpux11)
.so (sun58 and sun58_64)
.so (linux_x86 and linux_x86_64)
deviceidx.db
If a subcircuit model is in schematic form. circuit/designs .dsn files
Note
To see the value for $SIMARCH , choose Tools > Configuration Explorer from the ADS Main window. Locate SIMARCH in the ADS Configuration Explorer window's Status pane (you may need to scroll to locate it). Example values are: win32 , win32_64 , hpux11 , sun58 , sun58_64 , linux_x86 , and linux_x86_64 .

ADS Design Kit File Structure for Component Palette and Simulation Data in Model Files shows the directory structure of a design kit that provides a component palette and model data in the form of model cards or subcircuit models in a netlist file. This is a typical simple RFIC design kit. Additionally, it could include a circuit/records directory to enable the library browser.

ADS Design Kit File Structure for Component Palette and Simulation Data in Model Files
Note
The name design_kit__name_ as the top level directory name is a generic name supplied for these illustrations. This name should be replaced by the actual name of your design kit.

ADS Design Kit File Structure for Library Browser Access and Simulation Data in Data Files shows the directory structure of a design kit that provides access to components via the library browser and includes simulation data in the form of a data file.

ADS Design Kit File Structure for Library Browser Access and Simulation Data in Data Files

Comprehensive Listing of Potential Directories in an ADS Design Kit shows the comprehensive structure of all possible design kit directories defined at the time this document was written. If your design kit needs directories that are not listed in the complete structure shown here, it is recommended that you work with the ADS Design Kit Infrastructure team at Agilent EEsof EDA.

Comprehensive Listing of Potential Directories in an ADS Design Kit

Design Kit File Structure lists all of the possible subdirectories, as shown in Comprehensive Listing of Potential Directories in an ADS Design Kit, as well as the types of files that will reside in those directories. Note that the last column in Design Kit File Structure denotes whether the files are autoloaded (AL) or not.

Design Kit File Structure
Directories Subdirectories Files Description AL
bin/ $SIMARCH/ .dll (win32, win32_64),
.sl (hpux11),
.so (sun58, sun58_64),
.so (linux_x86, linux_x86_64),
deviceidx.db† 
User-compiled model in dynamically linked library or shared library. Y
circuit/ ael/ <prefix>_<item>.ael create_item() N*
  artwork/ *.ael macro files for ADS layout N
  bitmaps/pc/ <prefix>_<item>.bmp PC bitmap N
  bitmaps/unix/ <prefix>_<item>.bmp UNIX bitmap (bmptoxpm) N
  config/†  ADSlibconfig #uselib lookup table Y
  data/ *.ds simulations/measurements N
    *.mdf MDIF files generated by ICCAP Y
    *.s2p Touchstone S-parameter files Y
    *.cti CITIFILE files Y
  designs/ *.dsn subcircuits Y
  models/ *.net spice/spectre translator netlists N
    *.library encoded libraries Y
  records/ <prefix>_<lib>.ctl control file Y
    <prefix>_<lib>.rec record file Y
    <prefix>_<lib>.idf item definition file (hpedlibgen) Y
  substrates/†  substrate.slm, *.slm substrate files Y
  symbols/ <prefix>_<item>.dsn symbols Y
  templates/†  *.ddt, *.rec, *.ctl dds templates Y
    *.tpl schematic templates Y
config/   de_sim.cfg†  template config files N
de/ ael/ boot.ael generic N*
    palette.ael generic N
  defaults/ *.lay (schematic.lay and/or layout.lay) layers files Y
    *.prf (schematic.pdf and/or layout.prf) preference files Y
design_kit/   ads.lib template Y
doc/   readme.txt install info N
    about.txt menu info N
    index†  lookup file N
    <prefix>_<lib>.html†  component info N
drc/ rules/†    DRC rules N
examples/   *.zap archived ADS project N
expressions/ ael/†  dk_defined_fun.ael Design Kit expressions ael file Y
    *.ael expressions N
adsptolemy/†      adsptolemy dir N
lvs/†  ael/   layout vs. schematic N
  components/     N
scripts/†    *.pl scripts N
    *.ksh, *.bat   N
utilities/†    *.ael any auxiliary code N
verification/†      verification info N

AL = Files Autoloaded (Y/N)?
* Note that <prefix><item>.ael is loaded only if specified in boot.ael or if compiled into <prefix><lib>.idf. Also, boot.ael is loaded only when specified in ads.lib.
†  Optional part. For more information, refer to Additional Parts for ADS Design Kits.

Understanding the Directory Contents

This section briefly describes the files in each subdirectory of the complete ADS design kit structure. For a full description of each section, refer to the expanded discussion in Basic Parts of an ADS Design Kit or Additional Parts for ADS Design Kits.

The naming convention for some of the items in these tables is <prefix> _ <item> .ael or <prefix> _ <lib> .ael. The <prefix> name is a unique identifier that should include the foundry name and the process name. The <item> name refers to a component name and the <lib> name refers to a library name. For more information on naming conventions, refer to Component Name. Note that all names within angled brackets ( < >) are place holders and will be replaced by a real name in your design kit.

The '<design_kit_name>' Directory

The <design_kit_name> directory is the ADS Design Kit directory name. For more information on naming directories, refer to Design Kit Name.

The 'bin/$SIMARCH' Directory

The bin/$SIMARCH directory contains platform dependent subdirectories, where $SIMARCH = hpux11 , sun58 , sun58_64 , linux_x86 , linux_x86_64 , win32 or win32_64 . The directories contain dynamically linked libraries or shared libraries (*.dll/*.sl/*.so) and the device index file (deviceidx.db). The value of $SIMARCH can be determined by running the command:
$HPEESOF_DIR/bin/hpeesofarch
For more information, refer to User Compiled Models.

The 'circuit' Directory

For each design kit, there are quite a few possible circuit subdirectories that contain the files specific to a particular process. Details on the files in these subdirectories, are provided in The circuit Subdirectories.

The circuit Subdirectories
Subdirectory Description
ael Component definition files
The files in these directories are AEL files containing 'create_item()' statements, which are the item definitions for each component. Each component may be in a separate file or they may be combined into one file. The file may also contain global variable declarations, form definitions, or callback functions needed for each component. These files are loaded automatically only if there is no boot file specified in ads.lib and no .idf file in the circuit/records directory.
Files: <prefix>_<item>.ael
artwork Macro files for Component Artwork
This directory is provided for AEL artwork macro files for ADS layout.
Files: *.ael
bitmaps Component bitmap files
Each component has two versions of the same bitmap stored in two separate subdirectories. The file for the PC platform is in BMP format, and the file for the unix platform is in the XPM format. The file names should be the same between the two directories and should be stored in subdirectories named pc and unix. All files can have the .bmp extension, which cannot be given when the file is referenced in ael calls to dk_define_palette_group().
Files: <prefix>_<item>.bmp
config†  Component configuration files
The ADSlibconfig is a lookup file for locating a special type of ADS library. It is referenced by the simulator when a #uselib statement is encountered. A template version of ADSlibconfig can be placed in this directory when creating a design kit with encoded models or circuits (see "The RF IP Encoder and Design Kits").
The ADSlibconfig will be read by ADS from the following location. The design kit's included ADSlibconfig contents will be merged with the $HOME/hpeesof/design_kit/circuit/config/ADSlibconfig file automatically when the user loads the design kit into ADS.
The variable DKIT_ADSLIBCONFIG_PATH will be set in the user's $HOME/hpeesof/config/hpeesofsim.cfg file to $HOME/hpeesof/design_kit/circuit/config after the design kit is loaded by the user and the $HOME/hpeesof/design_kit/circuit/config/ADSlibconfig file is automatically updated with the design kit's ADSlibconfig file contents upon loading.
data Component data files
These files are an optional way to define simulation data. The typical way is to provide model files. This directory is provided to store ADS simulator dataset files (.ds), MDIF files (.mdf), CITIFILES (.cti) and Touchstone files (.s2p).
Files: *.ds, *.mdf, *.cti, or *.s2p
designs Component design files
The designs directory contains the design files (*.dsn) for hierarchical subcircuits that can be pushed into from the schematic view. Note that .dsn files are release dependent. so a .dsn file created in a certain version of ADS cannot be opened in a previous version. Design files can however be opened in later versions, so they should always be created in the earliest version of ADS that the design kit is supported for.
Files: *.dsn
models Component model files
This is the typical way to provide model data to the simulator. It is a file or set of files containing process variables and model cards or subcircuit model descriptions in the ADS netlist format. Typically these files are translated from Spectre or HSpice files with the ADS Netlist Translator. For more information on netlist translation, refer to the ADS "Netlist Translator for SPICE and Spectre" documentation.
Encoded libraries generated by the RF IP Encoder are also stored in this location. For more information, refer to "The RF IP Encoder and Design Kits".
Files: *.net, *.library
records Component records files
There are three types of files in the records directory. The .ctl file lists the names of the libraries in an XML file format. It also includes the name of a .rec file to read for each library. The .rec file is also in XML format and it lists specific information about each component in the library. These two files are used to build the library and component lists in the Library Browser. Only one .ctl file should be included and it can refer to multiple .rec files.
The third type of file in the directory is used for demand loading of components. It is a platform-independent hash file created from all the .ael item definition files for each component. Only one .idf file should be included in this directory.
The records directory is added to the DESIGN_KIT_BROWSER_PATH search path when a design kit is loaded. This variable is referenced by HPANALOGRF_BROWSER_PATH in hpeesofbrowser.cfg.
Files: <prefix><lib>.ctl; <prefix><lib>.rec; <prefix>_<lib>.idf
substrates†  Momentum substrate files
If a design kit contains substrate files for use with Momentum, this is the place to store them. Name the default substrate file of your design kit substrate.slm. This file (substrate.slm) will be read into all new designs that have set your design kit to be the technology source. The default substrate file makes up part of the design kit's technology files which currently includes preference, layer, and substrate files.
For more information on Momentum substrate files, refer to the "Momentum" documentation. The end user can use the New Design dialog box in ADS to read the default substrate file (substrate.slm) into a new design in the project and have them automatically associated with the new design. Alternatively, they can browse to open a substrate file with the Momentum user interface; however, they must be careful not to save any changes to a substrate file.
Files: substrate.slm and/or *.slm
symbols Component symbol files
The symbol files are design files containing the information needed by the system to draw the schematic symbol on the schematic page. The configuration variable SYSTEM_CUSTOM_CIRCUIT_SYMBOLS is modified on the fly when a design kit is loaded. The path is extended to include the path to these symbol files.
Files: <prefix>_<item>.dsn
templates†  Component template files
This directory can include templates for simulation or for data display. The path variable DESIGN_KIT_TEMPLATE_BROWSER_PATH is extended to include this directory when a design kit is loaded. This path variable is referenced by HP_TEMPLATE_BROWSER_PATH in hpeesofbrowser.cfg.
Files: <prefix><item>.ds or <prefix><item>.mdf

†  Optional part. For more information, refer to Additional Parts for ADS Design Kits.

The 'config' Directory

The <design_kit_name> /config is no longer required. It was used in the past to store a template version of the de_sim.cfg file that needed to be placed in the $HOME/hpeesof/config directory at the local level or $HPEESOF_DIR/custom/config directory at the system level. The variables defined in this file were necessary to load the old design kit software. This is no longer necessary as of ADS 2001. For more information on the de_sim.cfg file, refer to Configuration Files.

This directory may be used if a kit requires custom configuration variables but extensive use of these variables is discouraged. A script would have to be provided to extend configuration variables dynamically or move the file to a location where it will be recognized by ADS, and the script has to be smart enough to merge the file with existing files and specific variables with existing variables of the same name to avoid disabling other software. Details of this level of customization are not currently provided in this documentation. For more information on custom configurations, refer to Customization and Configuration.

The 'de' Directory

For each design kit, there are two possible de subdirectories that contain the files specific to a particular process. Details on the files in these subdirectories, are provided in the de subdirectories.

Subdirectory Description
ael AEL files
The <design_kit_name> /de/ael directory is to be used for AEL files that apply to the design kit in general, as opposed to the component specific files in circuit/ael. Some examples of files in this directory are boot.ael and palette.ael . These files contain commands used by the system to load the design kit and configure the component palette. More information about these files is included in Basic Parts of an ADS Design Kit. Sample versions of these files are included in the ADS Design Kit Tutorial.
Other AEL files may be put in this directory if the design kit requires custom AEL code. The utilities directory is also available for auxiliary AEL functions. ADS must be instructed to load these AEL files from boot.ael , as shown in Creating the boot.ael File, and boot.ael must be specified in the template ads.lib file.
Files: <prefix>_<item>.ael
defaults Layer and Preferences files
The <design_kit_name> /de/defaults directory can contain layer and preference files (.lay and .prf) which need to be used with the design kit. These files help make up part of the design kit's technology files which are currently preference, layer, and substrate files.
The schematic.prf file will determine the length units on many ADS built-in components such as microstrip lines. If you wish to establish the default length units for these, you should have a schematic.prf file in this directory. You can copy one of the schematic.prf.um, schematic.prf.mm, or schematic.prf.mil files in the $HPEESOF_DIR/de/defaults directory to establish µm, mm, or mil length units. A schematic.lay file in normally not used. The default schematic.lay file is in the $HPEESOF_DIR/de/defaults directory.
If your design kit will contain artwork for components you should include a layout.prf and layout.lay file in it. Details on the possible methods for handling this are included in Layers and Preferences Files.
For more information on layer (.lay) and preference (.prf) files, refer to Preference Functions in the AEL documentation.
Files: layout.lay, schematic.lay, layout.prf, and schematic.prf

The 'design_kit' Directory

The <design_kit_name> /design_kit directory contains a template version of the ads.lib file that needs to be installed to enable this design kit. For specific details on the ads.lib file, refer to The ads.lib Template.

The 'doc' Directory

The <design_kit_name> /doc directory contains all of the user documentation associated with the design kit. The only required file in the doc directory at this time is the about.txt file. HTML files may also be included and merged into ADS documentation. For more information on the about.txt file, refer to The about.txt File. For more information on adding HTML documentation to the system, refer to Creating Design Kit Documentation.

The 'drc' Directory

The <design_kit_name> /drc/rules directory contains ael files which define drc rules for the Design Rule Checker (DRC) tool in ADS. For more information on DRC in ADS, refer to Design Rule Checker.

The 'examples' Directory

Each design kit must include at least one sample design. This can be used by your customer or by Agilent Technologies support engineers to ensure that the design kit is installed correctly before they start a new design. You can use this as a method to demonstrate special features of the design kit such as a mandatory process component that must be placed in any design using the design kit. It is especially helpful if a design kit includes a custom version of the simulator to verify that the correct simulator is being used. For more information, refer to Adding Simulation Data to a Design Kit. The project or projects containing the sample design(s) are archived and then stored in the <design_kit_name> /examples directory.

The 'expressions' Directory

The <design_kit_name> /expressions/ael directory contains the file dk_defined_fun.ael which contains AEL expressions that can be copied into a schematic or data display for processing before or after simulation. For more information, refer to Expressions.

The 'adsptolemy' Directory

The <design_kit_name> /adsptolemy directory is not currently used by standard design kit software, however, it may be used by specific or custom design kit software.

The 'netlist_exp' Directory

The <design_kit_name> /netlist_exp directory contains all files needed by the ADS Netlist Exporter . By providing rules files for each component in a design kit, the Netlist Exporter can output netlists in the proper form for many LVS tools. For more information on incorporating the appropriate LVS information into a design kit, refer to Configuring Design Kit Components for use with ADS Netlist Exporter.

The 'scripts' Directory

The <design_kit_name> /scripts directory contains any custom shell or perl scripts that you have developed for use with your design kit. For more information on incorporating these scripts into your design kit, refer to Additional Parts for ADS Design Kits.

The 'utilities' Directory

The <design_kit_name> /utilities directory contains any custom AEL scripts that are auxiliary in nature. Other AEL scripts that are used directly with the design kit are stored in de/ael or circuits/ael as described in The_'de'_Directory_and_The_'circuit'_Directory._For_more_information_on_incorporating_these_scripts_into_your_design_kit,_refer_to_Additional Parts for ADS Design Kits.

The 'verification' Directory

The <design_kit_name> /verification directory contains files that are used by the ADS Design Kit Model Verification Toolkit to create a verification suite. These files are appropriate to ship along with the design kit. For more information on the verification tool, refer to Verifying a Design Kit.

 

Privacy Statement  | Terms of Use  | Legal | Contact Us  | © Agilent 2000-2008 

Contents
Additional Resources