Creating and Linking a Digital SimCode Model

Due to the complexity of digital devices it is generally not practical to simulate them using standard, non-event-driven SPICE instructions. For this reason Altium Designer's Mixed-Signal Circuit Simulator includes a special descriptive language that allows digital devices to be simulated using an extended version of the event-driven XSPICE. This language – used to model digital devices – is called Digital SimCode™. Digital SimCode is a proprietary language - devices created with it are not compatible with other simulators, nor are digital components created for other simulators compatible with Altium Designer's Mixed-Signal Circuit Simulator.

SimCode is a C like description language. You use it to define the characteristics and behavior of the device you are modeling. It includes functions to define parameters such as propagation delays, load characteristics, strengths, and so on. The device behavior is defined using truth tables, math functions and conditional control statements, such as IF..THEN statements.

To illustrate how to create a model using this language and then to link that model to a source schematic component, this article goes through the steps to create a new simulation-ready 74LS74 dual positive-edge triggered D flip-flop.

Creating the Schematic Component

Typically the first step when creating a new simulation-ready digital device is to create a schematic library component for that device and define the symbol graphics. This is done using Altium Designer's Schematic Library Editor, as shown below. For our example, the 74LS74 device has been drawn as a 2-part component. VCC (pin 14) and GND (pin 7) are defined as hidden pins. Often you will find it easier to copy an existing component and then modify it as required, rather than create the component and related graphics from scratch.

Defining the component in the Schematic Library Editor.

A Word about Digital Power and Ground

Digital devices include hidden power and ground power pins in each schematic symbol (VCC and GND for the TTL devices, and VDD and GND for the CMOS series devices). These hidden power pins are automatically connected during netlisting and assigned the voltages specified in the Digital Supply VCC and Digital Supply VDD fields, on the Advanced Options page of the Analyses Setup dialog (shown below). To change the default power supply values, enter new values in these fields. The defaults are VCC = 5V, VDD = 15V.

The Simulator uses these net names by default, so for a digital-only design it is not necessary to include sources to power these components. If the design includes any analog components that connect to the VCC (or VDD) power rail (perhaps a pullup), you must include an appropriate VCC or VDD source.

To power any digital components in your circuit from nets other than VCC (or VDD), you must include source components to create the appropriate voltages, un-hide the power pins for each component and wire the power pins to the appropriate power nets.

When a simulation is run, all data that is collected for all available signals is referenced to a specific net in the circuit. This net is defined in the Spice Reference Net Name field, also on the Advanced Options page of the Analyses Setup dialog (shown below) and, by default, is the GND net. To run a transient simulation which references a net other than GND, enter the net name in this field.

Specification of digital power sources as part of advanced analysis setup.

Writing the Source Code for the Digital SimCode Model

After creating the schematic component, the SimCode model for the device must be created. Later, the model will be linked to the component.

The source code for the required Digital SimCode model can be written using any ASCII text editor. Although the file can be given any name and extension, it is typically named the same as the device and given the .txt extension. For our example, the file will be named 74LS74.txt. Note that multiple device models can be defined in the same source file.

SimCode for the 74LS74

Following is the complete source code written to define the SimCode model used to describe the 74LS74 device. Copy and paste this code into an ASCII text editor and save the file as 74LS74.txt. For the purpose of understanding, the code is divided into sections, with an explanation of what is happening in each section provided after the code.

  //============================================================ //Section 1 # ls74 source //1/2- 74LS74 D flip-flop Digital SimCode Model //typical prop delay values from TI 1981 2nd edition data book //============================================================ //Section 2 INPUTS VCC, GND, PRE, DATA, CLK, CLR; OUTPUTS VCC_LD, PRE_LD, DATA_LD, CLK_LD, CLR_LD, QN, Q; INTEGERS tblIndex; REALS tplh_val, tphl_val, ts_val, th_val, trec_val, tt_val, temp_tp,       clk_twl, clk_twh, pre_clr_twl, ril_val, rih_val, ricc_val; PWR_GND_PINS(VCC,GND);     //set pwr_param and gnd_param values SUPPLY_MIN_MAX(4.75,5.25); //test for min supply=4.75 and max supply=5.25 VOL_VOH_MIN(0.2,-0.4,0.1); //vol_param=gnd_param+0.2,voh_param=pwr_param-0.4 VIL_VIH_VALUE(1.25,1.35);  //set input threshold values: vil and vih IO_PAIRS(PRE:PRE_LD, DATA:DATA_LD, CLK:CLK_LD, CLR:CLR_LD); //Section 3 IF (init_sim) THEN  BEGIN        //select prop delay, setup, hold, and width times   //NOTE: both ttlh and tthl are the same value   tt_val= (MIN_TYP_MAX(tt_param: NULL, 5n,  NULL));   temp_tp= (PWL_TABLE(sim_temp: -75, -5n, 125, 5n)); //tp temperature affect   tplh_val= (MIN_TYP_MAX(tp_param: NULL, 14n, 25n) + temp_tp);   tphl_val= (MIN_TYP_MAX(tp_param: NULL, 20n, 40n) + temp_tp);   ts_val= (20n);   th_val= (5n);   trec_val= (5n);   clk_twl= (25n);      //not specified - derived from fmax   clk_twh= (25n);   pre_clr_twl= (20n);   //LS stdout drive IOL max=8mA @ VOL typ=0.35V:rol_param=0.35V/8mA=43.75   //LS stdout drive IOL max=8mA @ VOL max=0.5V: rol_param=0.5V/8mA=62.5   rol_param= (MIN_TYP_MAX(drv_param: 62.5, 43.75,  NULL));   //LS stdout drive IOS min=20mA @ VCC max=5.25V: roh_param=5.25V/20mA=262.5   //LS stdout drive IOS max=100mA @ VCC max=5.25V:roh_param=5.25V/100mA=52.5   roh_param= (MIN_TYP_MAX(drv_param: 262.5, NULL, 52.5));   //LS input load IIH max=20uA @ Vin=2.7V: ril= (2.7-vol_param)/20uA=125k   ril_val= (MIN_TYP_MAX(ld_param: NULL, NULL, 125k));   //LS input load IIL max=-0.4mA @ Vin=0.4V:rih= (voh_param-0.4)/0.4mA=10.5k   rih_val= (MIN_TYP_MAX(ld_param: NULL, NULL, 10.5k));   //Icc @ 5V: 2500= 4mA/2 typical, 1250= 8mA/2 max   ricc_val= (MIN_TYP_MAX(i_param: NULL, 2500, 1250));   STATE Q = ONE;            // initialize output states   STATE QN = ZERO;   EXIT;  END; //Section 4 DRIVE Q QN = (v0=vol_param,v1=voh_param,ttlh=tt_val,tthl=tt_val); LOAD PRE_LD DATA_LD CLK_LD CLR_LD = (v0=vol_param,r0=ril_val,v1=voh_param,r1=rih_val,io=1e9,t=1p); //Section 5 EXT_TABLE tblIndex PRE CLR CLK DATA    Q     QN 0   1   X   X       H     L 1   0   X   X       L     H 0   0   X   X       H     H 1   1   ^   X       DATA  ~DATA 1   1   X   X       Q     ~Q; LOAD VCC_LD = (v0=gnd_param,r0=ricc_val,t=1p); //Section 6 IF (warn_param) THEN   BEGIN     IF (PRE && CLR) THEN       BEGIN         SETUP_HOLD(CLK=LH DATA Ts=ts_val Th=th_val "CLK->DATA");         RECOVER(CLK=LH PRE CLR Trec=trec_val "CLK->PRE or CLR");         WIDTH(CLK Twl=clk_twl Twh=clk_twh "CLK");         WIDTH(PRE CLR Twl= pre_clr_twl "PRE or CLR");       END;   END; //Section 7 DELAY Q QN =   CASE (TRAN_LH) : tplh_val   CASE (TRAN_HL) : tphl_val END; EXIT;

Section 1 – SimCode Function Identification

#ls74 source identifies the beginning of the SimCode source function for the 74LS74.

Section 2 – Data Declarations

This section consists of pin and variable declarations.

The INPUTS statement declares the names of the input pins. VCC and GND pins are included in this statement. The order specified here must be used when defining the pin mapping information (or node list) as part of the Netlist Template for the linked model.

The OUTPUTS statement declares the names of the output pins. Notice that the input pins are listed here as well, but with the suffix _LD. Input pins must also be declared as outputs so that the device can provide a load back on the driving circuitry. VCC pins are also included in this statement, but not GND pins. Again the order specified here must be used when defining the node list as part of the Netlist Template for the linked model.

The PWR_GND_PINS statement declares which pins will be used for device power and ground, and samples their voltage levels for later use in the SimCode.

Section 3 – SimCode Function Initialization

The IF (init_sim) THEN section is executed only once, at the beginning of the simulation. In this section we set the device characteristics that are not subject to change due to outside influences, such as data book specifications. The outputs states should also be initialized here to their "most likely" state. The EXIT command should be placed at the end of this section (prior to the END statement for the section).

Section 4 – LOAD and DRIVE Statements

These statements are used to declare the load and drive capabilities of the device pins.

Section 5 – Device Functionality

This section can vary dramatically from part to part. In this example an EXT_TABLE command has been used. Other device models use a variety of IF...THEN, STATE_BIT, NUMBER and other statements to define the logical function of the device.

Section 6 – Tests for Device Setup Violations

These tests warn of device setup violations which, in the real world, may cause a device not to function properly. In the simulation, the device will generally still function, but warnings, if enabled, will be displayed.

Section 7 – Output Delays/Post Events

The DELAY statements occur at the end of the SimCode function. These statements actually post the events to the Simulator to let it know that something has changed, and when these events are scheduled to occur, relative to the rest of the simulation. Timing (propagation delay) is assigned to each output based on the data book specifications, input stimulus and the functionality of the device.

Linking the SimCode Model to the Schematic Component

The schematic library component exists and the source code for the SimCode model has been written and saved to file. Now it is time to link the model to the component.

Creating an Intermediate Model File (*.mdl)

For a digital model, the schematic component is linked to the SimCode model by using an intermediate model file (*.mdl). The model file can be created in any ASCII text editor. Typically you would name the file the same as the SimCode model that it targets. Ensure that it is saved with the .mdl extension.

The model file includes a single .MODEL line and as many comment lines (starting with a "*" symbol) as required. The syntax of the .MODEL line is:

.MODEL ModelName xsimcode(file="{MODEL_PATH}SimCodeModelFile" func=SimCodeFunctionName [data="DataFile"] {mntymx})

.MODEL	Declares the model statement.
ModelName	The model name. The name used for the model file itself will typically be the same.
xsimcode	This entry specifies that the model type is a Digital SimCode model.
file=	Points to the SimCode model file. Initially the SimCodeModelFile entry will be that of the ASCII text file containing the uncompiled SimCode source for the device (*.txt). Once the model has been compiled, this entry can be changed to point to the compiled SimCode model file (*.scb). {MODEL_PATH} can be used as a shortcut to the directory specified in the Model Path field of the Simulation Preferences dialog. Access this dialog by clicking on the Preferences button in the Analyses Setup dialog. The directory specified is relative to the \Library directory. By default, the entry is set to Sim\, which means that {MODEL_PATH} will be substituted by RootDrive:\Library\Sim\ in the generated netlist. Either use {MODEL_PATH} and set Model Path to point to the location of the SimCode model file, or enter the full path information to the required location.
func=	Specifies the device's Digital SimCode function. SimCodeFunctionName is taken from the # xxxx source line of the SimCode.
data=	This optional entry points to a data file (*.dat) – represented by the DataFile entry – containing ASCII data for the SimCode READ_DATA function.
mntymx	Passes the device's digital model parameters into SimCode. These are parameters for the device that can be specified on the Parameters tab of the Sim Model dialog. This dialog can be accessed by double-clicking on the entry for the simulation model link in the Models region of the component's associated Component Properties dialog (see Linking to the SimCode Model). Any values specified on this tab for a device will be passed into and override those values declared in the SimCode model for that device.

For our 74LS74 example, the model file could contain the following definition:

*74LS74 Dual D-Type Positive-Edge-Triggered Flip-Flop with Preset and Clear

*Type: Digital PKG: D014 [DVCC=14;DGND=7;](A:4 2 3 1 6 5)(B:10 12 11 13 8 9)

.MODEL 74LS74 xsimcode(file="{MODEL_PATH}74LS74.txt" func=ls74 {mntymx})

and be saved as 74LS74.mdl. Notice that the func= entry of ls74 is taken from the # ls74 source declaration in the SimCode.

Linking to the SimCode Model

Having created the .mdl file, it is now time to create a link to the SimCode model – using this file – from the schematic library component. The first step in this process is to add a simulation model link to the component, carried out in the Schematic Library Editor in one of the following ways:

1. In the Models region of the Editor's main design window, click on the drop-down arrow associated with the lower-left button and choose Simulationfrom the list of available model types.
   
2. In the Models region of the SCH Library panel, click on the associated Add button and choose Simulation as the model type in the Add New Model dialog that appears.
   
3. Use the Model Manager dialog (Tools » Model Manager). Simply select the entry for the component, click on the drop-down arrow associated with the Add button, and choose Simulation from the list of available model types.
   

Whichever method you use to add a simulation model link to the component, you will be taken to the Sim Model dialog (shown below) – where the link to the required simulation model is configured.

Configuring the link to the SimCode model in the Sim Model dialog.

On the Model Kind tab of the dialog, ensure that the following are set/entered:

• Model Kind is set to General.
• Model Sub-Kind is set to Generic Editor. This is required so that you can enter and edit the netlist template applicable to the digital device represented by the SimCode model
• Spice Prefix is set to A (the prefix used for SimCode models).
• In the Model Name field, enter the name of the simulation model as specified in the intermediate .mdl file. Typically, this entry will be the same as the name of the .mdl file.
• An entry into the Description field is optional. You might enter SimCode here to distinguish that this link is to a SimCode model.

Considering our 74LS74 example, the entries in the dialog would appear as shown below.

Initial model settings for the 74LS74 example.

The Model Location region of the dialog will remain grayed-out at this time. Although we have the 74LS74.mdl file created, the file cannot be found (and the link established) until the netlist template for the model is entered. How this entry is built is detailed in the following section.

Specifying the Netlist Template

The netlist template defines how the information is entered into the XSpice netlist for a given component. As part of the process of linking the SimCode model to the schematic component, the template specific to that digital device being modeled must be defined. The definition is carried out on the Netlist Template tab, at the bottom of the Sim Model dialog.

The Netlist Template for a digital device takes the form:

@DESIGNATOR [input node list][output node list] @MODEL

where:

@DESIGNATOR will be replaced in the generated netlist by the designator of the component instance, with the Spice Prefix defined in the Sim Model dialog (e.g. AU1A)

@MODEL will be replaced in the generated netlist by the name of the intermediate model file specified in the Model Name field of the Sim Model dialog (e.g. 74LS74).

The [input node list] and [output node list] entries provide the pin mapping information. The nodes must be listed in the same order as the pins in the INPUTS and OUTPUTS statements in the SimCode. Referring back to the SimCode source for our 74LS74 example device, the inputs and outputs are specified as follows:

INPUTS VCC, GND, PRE, DATA, CLK, CLR;

OUTPUTS VCC_LD, PRE_LD, DATA_LD, CLK_LD, CLR_LD, QN, Q;

Use the component symbol to help define the pin list.

In order to effectively map the pins of the schematic component to these inputs and outputs declared in the SimCode file, we must first create an order – or pin list – for the component's pins. We need only consider the pin names and the method of ordering is not fixed. Typically, VCC and GND pins would be listed first, followed by all other pins starting at 12 O'clock and moving anti-clockwise.

Considering the schematic symbol for our 74LS74 example component, the pin list would be:

VCC, GND, PR, D, CLK, CLR, Q\, Q

Now we have a pin ordering for the component, we can go ahead and map the pins to obtain the input and output node lists for the netlist template. The easiest way to do this is to draw up a table. List the pins in the order they are required by the SimCode model, then write the position of each pin in the ordered pin list for the component. The tables below illustrate this for our 74LS74 device.

SimCode Input Pin	Position of pin in pin list	SimCode Output Pin	Position of pin in pin list
VCC	1	VCC_LD	1
GND	2	PRE_LD	3
PRE	3	DATA_LD	4
DATA	4	CLK_LD	5
CLK	5	CLR_LD	6
CLR	6	QN	7
		Q	8

From these tables the node lists can be written. A "%" prefix for each pin tells the Netlister to replace the entry with the name of the net to which the schematic pin (mapped to the model pin) connects.

For our 74LS74, the required netlist template entries become:

[input node list] = [%1 %2 %3 %4 %5 %6]
[output node list] = [%1 %3 %4 %5 %6 %7 %8]

and the overall entry for the Netlist Template becomes:

@DESIGNATOR [%1 %2 %3 %4 %5 %6][%1 %3 %4 %5 %6 %7 %8] @MODEL

Once the entry for the Netlist Template is entered into the Sim Model dialog, the Model Location region of the dialog will become available. Use this region to control where the model is searched for:

• Any – searches all valid model locations for a matching model.
• In File – only searches for a matching model in the specified .mdl file, along all valid model locations.
• Full Path – only searches for a matching model in the specified .mdl file, along the specified path.
• In Integrated Library – draws the model directly from the integrated library used to place the component instance. The integrated library must be available in a valid location.

Valid model locations consist of:

• Project Models – .mdl files added to the project
• Installed Models – .mdl files added to the Installed Libraries list
• Project Search Paths – .mdl files made available to a project by defining one or more search paths in the Options for Project dialog.

Once successfully linked, an entry for where the corresponding *.mdl file has been found will be displayed. The image below shows the Model Kind tab of the Sim Model dialog with the defined Netlist Template and Model Location information for our 74LS74 example.

Defined netlist template and model location setting for the 74LS74 example.

Mapping the Ports

Once the simulation model file has been linked to the schematic component, you need to ensure that the pins of the schematic component are correctly mapped to the pins of the model. This is carried out on the Port Map tab of the Sim Model dialog.

Ensuring correct component pin-to-model port mapping.

For each schematic pin, simply refer back to your ordered pin list – or the tables you created – and use the available drop-down to change the associated Model Pin entry accordingly. Make sure you check the mapping for each part in a multi-part device.

Parameters

If needed, parameters can be defined for the model at the component-level, on the Parameters tab of the Sim Model dialog. Click the Add button to create a new parameter entry, then name the parameter accordingly. Repeat this process for each required parameter.

Parameters for TTL and CMOS Logic Devices

For TTL and CMOS logic components, the following parameters can be added:

Parameter	Definition
Propagation	Device propagation delay. Set to MIN or MAX to use min or max data book values (Default = typical value).
Loading	Input-loading characteristics. Set to MIN or MAX to use min or max data book values. (Default = typical value).
Drive	Output-drive characteristics. Set to MIN or MAX to use the min or max data book values. (Default = typical value).
Current	Device current used to specify device power. Set to MIN or MAX to use min or max data book values. (Default = typical value).
PWR value	Power supply voltage. Specifying a value here will override any value specified by default in the SimCode model. If this value is specified, you must also specify a value for GND.
GND value	Ground supply voltage. Specifying a value here will override any value specified by default in the SimCode model. If this value is specified, you must also specify a value for PWR.
VIL value	Low-level input voltage. Specifying a value here will override any value specified by default in the SimCode model.
VIH value	High-level output voltage. Specifying a value here will override any value specified by default in the SimCode model.
VOL value	Low-level output voltage. Specifying a value here will override any value specified by default in the SimCode model.
VOH value	High-level output voltage. Specifying a value here will override any value specified by default in the SimCode model.
WARN	Set to ON to flag errors for: setup time, hold time, recovery time, pulse width, min-max frequency violation and min-max voltage supply violation. Errors are reported as long as the code for these conditions has been included in the SimCode model. (Default = OFF).

Testing the Digital Device

With the SimCode model now linked to the schematic component, the component needs to be placed and its functionality tested. Create a simple circuit to do this.

When you run the simulation, the SimCode source model is automatically compiled 'on-the-fly'. To create a compiled model file, ensure that the Create compiled SimCode output file option is enabled in the Simulation Preferences dialog. This dialog is accessed by clicking on the Preferences button in the Analyses Setup dialog. The compiled output is written to an ASCII text file – SimCodeFunctionName simlist.txt – which, by default, is stored in the same directory as the ASCII SimCode source model file itself (\Library\Sim). The output location can be changed as required using the SimCode Output field, in the Simulation Preferences dialog. The SimCodeFunctionName is taken from the func= entry in the .MODEL line of the intermediate .mdl file.

Consider our 74LS74 device example whose:

• SimCode source model file is named 74LS74.txt and stored in the {MODEL_PATH} location
• intermediate .mdl file contains the entry func=ls74.

The compiled model information is written to the file ls74 simlist.txt, stored in the same location as the 74LS74.txt file. This file also contains a listing of the execution order of the SimCode source model.

Refine the SimCode source model as required and continue testing until you have completely debugged the model. For information on setting up and simulating a design, refer to the article Defining & running Circuit Simulation analyses.

Creating a Compiled SimCode Model File (*.scb)

Once the SimCode source model has been tested successfully, you can extract the compiled model information from the SimCodeFunctionName simlist.txt file and create a compiled SimCode model file. This file can be named the same as its uncompiled ASCII counterpart, but has the extension .scb.

As a single *.scb file can contain the compiled information for multiple models, the name of the file might typically reflect the category or family of the devices contained within.

For the 74LS74 example, the imagw below shows the SimCode model in its compiled form, which can be copied and saved into a file named 74LS74.scb, stored in the same location as the ASCII source model file.

Resulting compiled SimCode model.

The file= parameter in the .MODEL line of the intermediate .mdl file must then be changed to point to this compiled file. For the 74LS74.mdl file, the .MODEL entry will become:

.MODEL 74LS74 xsimcode(file="{MODEL_PATH}74LS74.scb" func=ls74 {mntymx})

Using the compiled SimCode model file will increase the speed of the simulation, as the Simulator does not have to recompile the source code each time.

Example SimCode Model Files

All of the SimCode source (*.txt) and compiled (*.scb) model files can be found in the Sim folder of the installation (\Library\Sim). These include the main compiled model files for TTL (LS.scb) and CMOS (CMOS.scb) devices. In addition, sub-folders containing example SimCode source model files for the following device manufacturers are available:

• Fairchild
• National Semiconductor
• ST Microelectronics
• Texas Instruments.

Example Circuits

There are a number of example projects available that demonstrate the use of digital devices and linked SimCode model files. Click the All Examples in single file link on the Download Examples and Reference Designs page to access the examples, located in the \Examples\Circuit Sim folder of the ZIP file. The following examples demonstrate the use of SimCode models:

• BCD-to-7 Segment Decoder (BCDto7.PrjPcb)
• Mixed-mode Binary Ripple 93 (Mixed-mode Binary Ripple 93.PrjPcb)
• Mixed-mode Binary Ripple 555 (Mixed-mode Binary Ripple 555.PrjPcb)
• Oscillator (Oscillator.PrjPcb)
• Schmitt Trigger Oscillator (Schmitt Trigger Oscillator.PrjPcb)
• State Machine (State.PrjPcb).