Customizing a Netlister

You can customize the Front End Flow netlister. You can automatically include files and add value mapping functions to those described in Front End Flow Functions. You can also add netlist exporting functions to those already in the Front End Flow API. And, you can override many of the functions listed in Appendix A, Front End Flow Functions.

Setting Up Automatically Included Files

Setting Up Automatically Included Files

The simplest method of customizing a netlister is setting up files that are automatically included in the final netlist.

Note Refer to the Netlist Exporter manual for the process for excluding included files.

The Include File Path

You should include files that set the options for a particular process or create the subcircuits necessary for a foundry process.
Any file in the following directories will be included in the Front End Flow netlist, unless you set them up to be excluded:

• {%CNEX_INSTALL_DIR}/include/{%CNEX_TOOL}
• {%CNEX_CUSTOM_DIR}/include/{%CNEX_TOOL}
• {%CNEX_HOME_DIR}/include/{%CNEX_TOOL}
• Any design kit path that contains the directory netlist_exp/include/{%CNEX_TOOL}

Example 1: Including a File Site Wide

You are using the Dracula tool and have set the variable CNEX_INSTALL_DIR to be $HPEESOF_DIR/netlist_exp . Place the file standard.inc in the directory CNEX_INSTALL_DIR/include/dracula . Whenever you create a netlist for Dracula, standard.inc will be included. If you use a different tool, the file will not be included.
CNEX_INSTALL_DIR is available to all site users, therefore standard.inc will be an included file for all who use the ADS installation on that site. If the ADS installation is on a shared drive that all users access, the included file will be automatically available to those users.

Example 2: Foundry Kit Include File

You have a foundry design kit from Foundry A that has the file foundryAOptions.inc , and you are using Dracula. Place the file in netlist_exp/include/dracula . When you run Dracula, foundryAOptions.inc will be automatically included.

Adding Value Mapping Functions

When the tool you have chosen uses a different type of name than does ADS, or when that tool uses different parameters or values than does ADS, you must write an AEL value mapping function to supply the tool with the correct output.

Case 1: Name Mapping

Use ADS model names that indicate what the component is, such as myAdsRes1 . However, Dracula only allows two character model names. Map the ADS name to a two character name that Dracula recognizes.

Case 2: Parameter Mapping

A single parameter in ADS may need to map to multiple parameters in another tool, or multiple parameters in ADS may need to map to a single parameter.For example, in ADS the _V_1Tone_ device has the parameters voltage and frequency. If you use the HSpice tool, you must map those parameters to the single SIN function for the correct HSpice output.

Case 3: Parameter Value Mapping

You may need a function that performs an operation on a parameter that is a value in ADS and returns a value that is mapped to a parameter in another tool. For example, you want to map the ADS temperature parameter to the differential dtemp parameter in HSpice. This requires a function that sets the ADS parameter value to the absolute temperature set in ADS and subtracts the circuit temperature. The function returns a value that contains the differential temperature and maps it to dtemp .

Function Prototype and Example

You must write all AEL value mapping functions. All value mapping functions receive an ADS parameter value and return the correct tool value. They all use the following prototype:

defun <function name> (value)

{
<your code here>
return(<new value>);
}

In addition to the parameter value you pass to the function, you must set the following three global variables:

• cnexCurrentRep
  This is a handle to the schematic that is currently being processed. The handle can be used to obtain data about other instances in the circuit.
• cnexCurrentInst
  This is a handle to the instance that is currently being processed. The handle can be used to get instance data, or data for other parameters.
• cnexCurrentParam
  This is a handle to the parameter that is currently being processed. Parameter attributes can be obtained by referencing this handle.

Example1: Writing a Type Mapping Function

defun myFoundryAddQuotes (value)

{
decl newValue=value;
if(is_string(value))
{
newValue=strcat("\"", value, "\"");
}
return(newValue);
}

This function adds quote marks around the ADS value passed to it.

Accessing Parameter Values Other Than the Current Parameter Value

In certain cases, it is necessary to access parameter values other than the current parameter value. This can be used to create an expression of multiple parameter values. An example of this would be a component that has Width and Length parameters, but the output netlist requires that an area parameter be output which is equal to the Width times the Length. The function cnexGetParamValueByName() was added in ADS 2003A. Using this function, the name of the desired parameter is passed in, and the value is returned.

Example

defun myFoundryArea (value)

{
   decl Width=cnexGetParamValueByName("Width");
   decl Length=cnexGetParamValueByName("Length");
   if(Width && Length)
   {
      return(strcat(Width, " * ", Length));
   }
   return("");
}

Adding the New Netlist Function

To add an instance netlist function, edit the component definition file for your component by adding a line with the syntax: Parameter_Type_Mapping = <param> <function> .

Example1: Adding the Function to the Component Definition File

You have an ADS component named myNpn which has a parameter named Model . You are using the type mapping function myFoundryAddQuotes .

1. Open the file the component definition file myNpn.cnex .
2. Add the line: Parameter_Type_Mapping = Model myFoundryAddQuotes
   When an instance of myNpn component is netlisted, the parameter value for Model will have double quotes around it.

Placing the Type Mapping Function

The configuration variable CNEX_EXPORT_FILE_PATH specifies the path where ADS searches for AEL files. During netlist exporting, ADS loads files named cnexGlobals and cnexNetlistFunctions located in that path.

AEL has a single name space for all of its variables and functions. All files named cnexGlobals or cnexNetlistFunctions in any path contained in the CNEX_EXPORT_FILE_PATH use this space. Therefore any AEL function has access to all AEL variables and functions.

These functions can be added in at any time. Every time the Front End Flow netlister is executed, all of the cnexNetlistFunctions and cnexGlobals AEL files are loaded.

Note See Configuration Files for more information on CNEX_EXPORT_FILE_PATH.

Example 1: Placing the Function

You want to place the function myFoundryAddQuotes so that Front End Flow can use it. Add a file named cnexNetlistFunctions to the directory {%CNEX_INSTALL_DIR}/ael/{%CNEX_TOOL} . If you wrote the function for HSpice, the directory would be $HPEESOF_DIR/netlist_exp/ael/HSpice . The next time that a Front End Flow netlist is generated, the myFoundryAddQuotes function will be available.

Validating a Type Mapping Function

Once the files have been loaded by creating a Front End Flow netlist, you can validate your function interactively using the ADS Command Line window. Bring up by selecting the menu option Options > Command Line from the main window. Enter an AEL function in the command line and you will see the value the function returns.

Validating Functions that Do Not Use Global Variables

Simple type mapping functions that do not require global variables to be set can be tested rapidly by using the info command and typing the function into the Command Line . This is shown in Accessing the AEL Command Line to Verify Functions.

Accessing the AEL Command Line to Verify Functions

1. Enter the function in the Command Line window.
2. The resulting return value appears in the Information window when you use the info dialog .

   Note The info dialog is modal and stops the execution of any further AEL operations.

   Validating Functions That Do Use Global Variables
   Use the fputs function and specifying stderr as the destination of the output. The fputs command using stderr will output text to the xterminal window from which ADS started.

1. Type the command fputs(stderr, myFoundryAddQuotes("myModel")) in the command line.
2. The result will display in the xterminal window.

   Note If you are running Front End Flow on a PC, be aware that it has no xterminal window. However, if you run ADS with the -d option you will have a debug window in which you can see the stderr output. The debug window will also display inter-process function call text.

   If the function needs global variables, add fputs(stderr, value) calls in your code.

Using Some Other Debugging Tips

• The identify_value function converts any AEL expression passed to it into a string. It is useful if you have values that are set to NULL, or if you are debugging lists because the fputs command only outputs strings.
• For formatted debugging output, you use fprintf(stderr, ...) . The fprintf function in AEL utilizes the same formatting strings as the Ansi C fprintf function.

Adding New Netlist Exporting Functions

The Front End Flow API provides 8 instance netlist exporting functions. Although these functions provide the correct output for nearly any ADS instance, there are some situations where you must write your own function in order to have the correct output. Some examples of this are outputting multiple instead of single components to a netlist file, and outputting a library or directive with a component.

Function Prototype and Example

All instance netlist exporting functions must have the following function prototype:

defun <function name> \(instH, instRecord\)

{
<your code here>
return(<string>);
}

• The parameter instH is the handle to the instance that is currently being formatted.
• The instRecord parameter is a list of lists that contains the information obtained by reading the component definition file for the instance.
• The return string is the value you wish to be output to the netlist file.

Example1: Writing a Type Mapping Function

defun myNpnInstance (instH, instRecord)

{
decl net="";
decl netReturn=cnexNetlistInstance(instH, instRecord);
net=strcat(".lib `MYMODELS' npn\n", netReturn);
return(net);
}

The function myNpnInstance causes the myNpn component to output a .lib statement when the instance is netlisted. The myNpnInstance function calls the cnexNetlistInstance function to get the instance netlist exporting line. The result from cnexNetlistInstance is then concatenated with the .lib statement. The result is then returned.

Using the New Netlist Function

To use an instance netlist function, you must edit the component definition file for your component by adding a line with the syntax: Netlist_Function = <function> .

Adding the Function to the Component File

Open myNpn.cnex , component definition file for myNew , and change the line Netlist_Function is changed so it reads:
Netlist_Function = myNpnInstance
The myNpn component will now use the newly created instance netlist exporting function.
More detailed examples can be found in Hspice Netlister Example.

Placing a New Netlist Exporting Function

The configuration variable CNEX_EXPORT_FILE_PATH specifies the location where ADS searches for AEL files. During netlist exporting, ADS follows the path and loads files named cnexGlobals and cnexNetlistFunctions.

AEL has a single name space for all of its variables and functions. All files named cnexGlobals or cnexNetlistFunctions in any path contained in the CNEX_EXPORT_FILE_PATH uses this space. Therefore any AEL function has access to all AEL variables and functions.

These functions can be added in at any time. Every time the Front End Flow netlister is executed, all of the c nexNetlistFunctions and cnexGlobals AEL files are loaded.

Note See Configuration Files for more information on the CNEX_EXPORT_FILE_PATH.

Adding the New Instance Netlist Exporting Function to a File

You want to place the function myNpnInstance . Add a file named cnexNetlistFunctions to the directory {%CNEX_INSTALL_DIR}/ael/{%CNEX_TOOL} . If you wrote the function for HSpice, the directory would be $HPEESOF_DIR/netlist_exp/ael/HSpice . The next time that a Front End Flow netlist is generated, the myNpnInstance function will be available.

Overriding Existing Front End Flow API Functions

Front End Flow provides API netlister functions for three tools: Dracula, Calibre, and Assura. Front End Flow Functions describes these functions. If you use a different tool, you should override the default API functions relevant to the correct output for your tool. To override means to keep the name of the default API function, but to modify its code so that it provides the correct output for your tool.

It is better to override the existing API functions than to write a new one with a new name. The reason is that end users may need to modify standard ADS component definitions so that they can map into your foundry process. These standard ADS components use the default API function names. If you use new API function names, the end user will not know the use of the new function, unless you supply that information. If you override the default functions, the end user can use the standard Front End Flow documentation.
You can override the functions at any time. Every time the Front End Flow netlister is executed, all of the cnexNetlistFunctions and cnexGlobals AEL files are loaded.

Function Prototype

To override a Front End Flow API function, you must make sure to follow the function prototypes that are defined in Front End Flow Functions.

• Whenever you override, you must use the same argument list and return name as the default function.
• There are some core functions in Front End Flow that will call the API functions directly. Those functions cannot be overridden.

  Note If the functions called by the Front End Flow core return incorrect names, or receive the wrong arguments, the Front End Flow netlister will error out and no netlist will be produced.

Example 1: Overriding the Top Cell Header Function

The function that controls how the top cell is output is the Front End Flow API function cnexOutputTopcellHeader. The values it receives are the design name and the design handle. For the Dracula-spice netlister, the function simply calls the subcircuit header function, which will cause a .subckt line to be created for the top cell as follows:

defun cnexOutputTopcellHeader(designName, dsnH)

{
    return(cnexOutputSubcircuitHeader(designName, dsnH));
}

For HSpice, the .subckt line is not required. In this case, override the default API function to output nothing for the top cell header:

defun cnexOutputTopcellHeader(designName, dsnH)

{
    return("");
}

Place this function into a file called cnexNetlistFunctions . Put this file in an HSpice subdirectory in one of the CNEX_EXPORT_FILE_PATH directories. When a netlist is created for HSpice, it will no longer use the default top cell function, it will use the API function that was modified for HSpice.

For more detailed examples of overriding API functions, refer to Hspice Netlister Example.

Function De

Subclassing a Function Definition

You may want to simply add a feature to an existing API function instead of overriding it. This is called subclassing a function.

In AEL, everything can be accessed as a variable, including functions. If you create a variable and set the variable equal to a function, you can call the variable value just like it was the function name. To save the function so you can access it later, you need to define the AEL variable as a global variable.

You can also create a variable and store a function to the variable, then override the function. The old definition is still in memory, and can be accessed through the variable. To save the function so you can access it later, you need to define the AEL variable as a global variable, and you must set the variable value prior to creating your new function.This is similar to accessing a parent method in C++, but the functions are not stored in classes.

Example 1: Subclassing an Original AEL Function

You have a function called cnexOutputTopcellHeader . You do not want to change how the function works, you just want to add a comment to it. The following code maintains the original function and adds your comment:

decl originalCnexOutputTopcellHeader=cnexOutputTopcellHeader;

defun cnexOutputTopcellHeader(designName, dsnH)

{
decl net=originalCnexOutputTopcellHeader(designName, dsnH);
decl returnNet="* Subclassed the original function to add this comment\n";
returnNet=strcat(returnNet, net);
return(returnNet);
}

The first line creates the global AEL variable originalCnexOutputTopcellHeader and assigns it the value cnexOutputTopcellHeader .

Note The function value is a memory pointer, so the global variable points to the same memory location as cnexOutputTopcellHeader . Once you have assigned the variable value, you can call that variable as if you had used a defun call to create a brand new function.

The fifth line adds the comment to the value generated by the function to which the variable originalcnexOutputTopcellHeader points, the function cnexOutputTopcellHeader .