1 Electronic Design Description Automation

EDDA

Fredrik Jonsson

December 7, 2007

CVS revision 1.4

1 Electronic Design Description Automation

The EDDA documentation system is a collection of scripts created to simplify theprocess of running ocean simulations and create design documentation.

The system consists of two parts:

1. Skill scripts to be used in the Cadence OCEAN environment to launch simula-tions and log simulation results.

2. The PlainDoc script pddd (based on the pd2tex tool written by Sampo Kel-lomäki) to capture the simulation results into graphs and tables and create hu-man readable design documentation (HTML and PDF documents).

PlainDoc is a tool to convert text files having a to nicely formatted HTML andPDF documents. PlainDoc is powerfull enough to allows the user to createcross references, insert figures, tables and equations.

An example EDDA design description may look like this.

There are several advantages using the documentation system:

• Speed up documentation process. Simulation results are automatically com-pared to specification and inserted into the simulation document. This min-imise the risk of human errors.

• Batch simulations over several corners can easily be simulated over nightusing scripts.

1

EDDA 1 ELECTRONIC DESIGN DESCRIPTION AUTOMATION

• Simple to update results. When a schematic is modified or model file isupdated the simulation script can be relaunched and all new results are au-tomatically inserted into the documents.

• Both HTML and PDF documents are automatically created for easy sharingof information within design group.

This tutorial is written using PlainDoc by Fredrik Jonsson. You can view thesource of this document here.

If you have any comments or suggestions, please contact me at

f [email protected] (1)

Also, it would be interresting to know if you sucessfully used EDDA in a project

1.1 Download

Click on this link to download EDDA.

Extract the tar file using

> tar -zxvf edda.tar.gz

Copy the file edda/log_data.il to a directory where you store SKILL files, andput the file edda/pddd in your executable search path.

The EDDA system use a number of Unix tools like Perl, LaTeX and image mag-ick when creating the documents. Most of these tools are standard on commonLinux distributions. If the tools are not available they have to be downloaded andinstalled separately.

EDDA have succesfully been tested on sevral different Redhat, Fedora and Cyg-win installations.

1.2 License

The EDDA documentation system is created by Fredrik Jonsson.

The EDDA version of PlainDoc is an extension of the PlainDoc tool created bySampo Kellomäki.

Information about PlainDoc can be found at http://mercnet.pt/plaindoc/pd.html

EDDA is offered under the Gnu Public License (GPL).

December 7, 2007 Fredrik Jonsson page 2

EDDA 2 USING EDDA

2 Using EDDA

Below will follow a short overview how to run simulations and create design doc-umentation using EDDA. In order to use the EDDA system it is assumed you arefamiliar with running Cadence simulations using Ocean. For information regard-ing how to configure these tools, please read the cadence documentation.

To create a EDDA document from an existing Cadence simulation testbench weneed to:

1. Create a documentation directory where the simulation files and documentswill be generated

2. Create an OCEAN simulation script file and run the simulations

3. Create a PlainDoc document

4. Generate the HTML and PDF documents

The following chapters will explain each step.

2.1 Directory structure

Since the EDDA system generates a large number of files the simulations anddocuments are created in a special directory structure. An example directory lookslike figure 1

Figure 1: Directory structure

The doc_directory is the documentation directory. This directory can have anyname and location.

The .pd directory stores temporary information when running PlainDoc.


EDDA 2 USING EDDA

corners store files defining the different simulation corners.

html will contain the HTML output

Simulations scripts are stored in testbench directories. The testbench directorycontains the netlist and the Ocean scripts. In the testbech directory a subdirectoryfor each simulation corner will be created containing simulation results. A doc-umentation directory can contain any number of testbenches, but each testbenchdirectory can only have one netlist.

The tex directory contains temporary data when creating a PDF document usingLaTeX.

Finally edda.pd is the document source file. The generated HTML and PDFdocuments will have the same name as the source file.

The directory structure can be generated using the command:

> pddd -init


EDDA 2 USING EDDA

2.2 OCEAN file

When running a cadence within the Virtuoso analog design environment you cancreate an OCEAN script using the menu command Session->Save Script ...

In order to use the OCEAN script in the EDDA environment you need to modifythe script according to the following steps:

1. Move corner definitions to a corner file

2. Create a symbolic link to the netlist in the testbench directory

3. Remove information regarding simulator and result directory

4. Add commands to log simulation results

The steps will be described in more detail below:

A typical automatic generated OCEAN script can look like this:

ocnWaveformTool( ’wavescan )simulator( ’spectre )design( "/home/fjon/simulation/simple/spectre/schematic/netlist/netlist")resultsDir( "/home/fjon/simulation/simple/spectre/schematic" )modelFile(

’("/pkg/designkits/umc/MM018/MM180_REG18_V123.lib.scs" "tt"))analysis(’ac ?start "1k" ?stop "100M" )analysis(’dc ?saveOppoint t )desVar( "Vsupply" 1.8 )temp( 27 )run()ACmag = dB20(VF("/out"))plot( ACmag ?expr ’( "ACmag" ) )Vdc = VDC("/out")plot( Vdc ?expr ’( "Vdc" ) )

This example script run an simple AC and a DC simulation and plots the result.We will now copy this file to the testbench directory and modify it to be compati-ble with EDDA.


EDDA 2 USING EDDA

2.2.1 Corner file

In order to use the script in the EDDA environment we first extract the cornerdefinition. The corner definition files are located in the corners directory. Thecorner file can have any name, but the the name typ is reserved for the typicalcorner.

Extracting the corner information from the example OCEAN file into a corner file.The final file corners/typ may look like this:

modelFile(’("/pkg/designkits/umc/MM018/MM180_REG18_V123.lib.scs" "tt")

)desVar("Vsupply" 1.8)temp( 27 )

2.2.2 Create symbolic link

The sim script will look for a link to the netlist in the test bench directory. Whennot using EDDA the design will be loaded using the line

design( "/home/fjon/simulation/simple/spectre/schematic/netlist/netlist")

in the ocean script. The actual location of the design file of course depend on thecadence configuration and the user. The design definition must be removed fromthe script file and be replaced by a symbolic link.

The symbolic link is created using the Unix command

> cd testbench1> ln -s home/fjon/simulation/simple/spectre/schematic/netlist/netlist .

Don’t forget the . at the end of the line.

2.2.3 Remove simulator and directory information

The sim script automatically configures the simulator and results directory so thisinformation can be removed from the scripts file.

Remove the lines


EDDA 2 USING EDDA

ocnWaveformTool( ’wavescan )simulator( ’spectre )design( "/home/fjon/simulation/simple/spectre/schematic/netlist/netlist")resultsDir( "/home/fjon/simulation/simple/spectre/schematic" )

from the script file.

The sim script will use the directory /tmp/USER/simulation/SCRIPT to storesimulation results, where USER and SCRIPT will be replaced by the user name andname of the script file.

2.2.4 Log simulation results

The EDDA system have a set of skill functions to log simulation results. Scalardata can be stored using log_data and waveforms are stored using log_wave.Data from simulation loops can be combined to generate a waveform using log_data_point.

The simulation results are stored as text files within the testbench directory. Asubdirectory for each corner will be generated.

To log the DC voltage and the AC response in the example ocean script we canuse the following lines:

log_data(VDC("/out") "Vdc")log_wave(dB20(VF("/out")) "ACmag")

If simulation is performed using these commands in the typ corner the files testbench1/typ/Vdcand testbench1/typ/ACmag will be created.

Plot commands from the original ocean script can be removed.

Now all the modifications to the script file is ready and the final script testbench1/script.ocnmay look like this:

analysis(’ac ?start "1k" ?stop "100M" )analysis(’dc ?saveOppoint t )

run()

log_data(VDC("/out") "Vdc")log_wave(dB20(VF("/out")) "ACmag")


EDDA 2 USING EDDA

2.3 Running the simulation

The simulation script are simulated using ocean. Start ocean within the testbenchdirectory.

> cd testbench1> ocean

Load the EDDA skill functions using

> load "log_data.il"

Now we can run the simulation using

> sim "script.ocn"

If we don’t specify a corner the default corner "typ" will be used. To specifyanother corner we can type

> sim "script.ocn" "fast"

Assuming we have a cornerfile named "fast" in the corners directory.

If the schematic is modified we recreate the netlist from Analog artist using themenu Simulation->Netlist->Recreate

To rerun the simulation script using the previous script file and corner it is enoughto type

> sim

A batch simulation simulating many corners can be created, for example by cre-ating a file all containing the lines

sim "script.ocn" "typ"sim "script.ocn" "fast"sim "script.ocn" "slow"

and simulating this file using

sim "all"

will simulate over corners typ, fast and slow.


EDDA 2 USING EDDA

2.4 Creating the simulation report

The simulation results can be documented in a design document. The documentis written in PlainDoc which is a simple text-file containing a few special "tags"to include simulation results, plots, equations, schematics etc.

2.4.1 Document structure

In the document we first insert the document title:

Example simulation##################

After this we insert information indicating the paper format, information aboutthe author etc:

<<class: article!a4paper,12pt>><<author: Fredrik Jonsson>>

Plain doc use a very simple yet powerful markup structure. Different headings areindicated by the way they are underlined:

1 Heading 1===========

1.1 Heading 2-------------

1.1.1 Heading 3~~~~~~~~~~~~~~~

The numbers at the beginning of the line are ignored when compiling the docu-ment, and sections are renumbered automatically.

Lists is created by inserting a * or a number at the beginning of a line

* Bulted list

1. Numbered list2. Item 2


EDDA 2 USING EDDA

Bold italic and computer output is created by inserting *+ or around a word:

*Bold* +italic+ and ~computer~ output.

Verbatim text blocks

Verbatim text

is created by inserting a single space at the beginning of a line.

Lines beginning with a % are commented out and will not be included in theoutput documents.

For more detailed information about the PlainDoc syntax, please see the appendixor the PlainDoc documentation.

2.4.2 Inserting simulation results

Simulation results are inserted using the tags data and plot.

Scalar data is inserted into a table like table 1

Spec ResultParameter Min Typ Max Min Typ Max Unit Pass

DC voltage 0.7 0.9 1.1 0.80slow 0.90 1.00 f ast V

Table 1: Simulation result summary

using the data command:

The slow and fast tags indicates in which corner the simulation result was found.

To insert the DC voltage from the previous simulation we can use the followinglines:

<<data:Simulation result summary:result1dir=testbench1Vdc,DC voltage,minmax,0.7,0.9,1.1,V,2>>

The first line

<<data:Simulation result summary:result1


EDDA 2 USING EDDA

specifies the beginning of a data section. The "Simulation result summary" is thecaption of the table, and "result1" is a tag that can be used to reference the table.

The next line

dir=testbench1

specifies from which directory the results will be picked. If this line is omitted alldirectories will be scanned for simulation results.

The line

Vdc,DC voltage,minmax,0.7,0.9,1.1,V,2

specifies data, unit and limits according to the syntax:

Variable, Caption, Spectype, Min, Typ, Max, Unit, Precision

Variable is the name of the variable specified in script file to store the data.The data table can contain any number of variable specifications.

Caption is a short text describing the variable.

Spectype specifies how the results will be compared to the specification. Cur-rently only the spectype minmax is allowed.

min, typ, max is the specification. Simulation results will be compared to thesevalues, and if outside the limit the label "FAIL" will be written in the Pass col-umn. If a parameter have no specification the specification field can be left blank,however the comma signs must not be removed

Unit specifies the unit of the parameters. Values are automatically scaled accord-ing to the unit prefix. If we for example specifies the unit to mV the simulatedresult will be multiplied by a factor 1000 before inserted into the table. Specifi-cation values are not scaled and should be specified in the correct unit, i.e. if thelimit is 42mV we should use 42 in the specification.

Precision specifies the numerical precision in the tabled.


EDDA 2 USING EDDA

-40

-35

-30

-25

-20

-15

-10

-5

100 1000 10000 100000 1e+06 1e+07 1e+08

gain

[dB]

Frequency [Hz]

ACmag:fastACmag:slow

ACmag:typ

Figure 2: AC gain

2.4.3 Waveforms

Plots like the one in figure 2 are inserted using the command plot

The plots are created using gnuplot. By clicking on a plot in the HTML documenta magnified version of the graph is presented.

To plot the AC magnitude in the example simulation we use the following line:

<<plot:set logscale xACmag,AC gain,Frequency [Hz],gain [dB],linewidth 5>>

The syntax of the plot command is:

waveform(s), Title, X label, Y label, Plot option

waveform is the waveforms to be plotted.

Title is the title of the plot


EDDA 2 USING EDDA

X axis and Y axis is the labels on the x and y axis.

The set and Plot option commands can be used to specify plot options in gnuplot.All Gnuplot set and unset commands can be used to control the graph. Anotheruseful set command is

set xrange [10:100]

that can be used to control the range on the axis.

For more details regarding available set commands, please refer to the Gnuplotdocumentation at http://www.gnuplot.info/

Several plots can be specified in one plot statement by adding plot specifications.Set commands must be specified for each plot.

Several waveforms can be plotted in the same graph by putting an & between theplot names. No space is allowed between the names. Specific simulation cornerscan be selected by putting the corner in parenthesis after the waveform name. Thewaveform caption can be specified by putting the caption within "". The corner isomitted from the caption if only simulation result from one corner is found.

Example: The following example creates two plots. The first plot (Figure 3) havetwo waveforms, the first incluing data from the typ and slow corner and label it"Mag" and the second fast corner and label it "Gain fast".

The second plot (Figure 4) is a zoomed in version haing only one wave from theslow corner.

<<plot:set logscale xACmag(typ slow)"Mag"&ACmag(fast)"Gain fast",AC gain,Freq,gain

set logscale xset xrange [1e5:1e7]ACmag(slow)"Gain",AC gain,Freq [Hz],gain [dB]>>

By default simulation data from all available corners and testbench directories arecollected. You can specify a specific corner or directory by inserting dir andcorners lines the same way as in the data table.

If we only want the typ corner from testbench1 we can write:

dir=testbench1corners=typ


EDDA 2 USING EDDA

-40

-35

-30

-25

-20

-15

-10

-5

100 1000 10000 100000 1e+06 1e+07 1e+08

gain

Freq

Mag:typMag:slowGain fast

Figure 3: AC gain

-18

-16

-14

-12

-10

-8

-6

100000 1e+06 1e+07

gain

[dB]

Freq [Hz]

Gain

Figure 4: AC gain


EDDA 3 EXAMPLE

2.5 Generating the HTML and PDF outputs

The HTML and DPF outputs are generated using the command

> pddd example.pd

The HTML document by viewed by opening the file html/index.html in a webbrowser. The PDF document is copied both to the HTML directory and to thedocumentation directory.

3 Example

An example EDDA design description may look like this. The document is gen-erated using the following source file.


EDDA 4 APPENDIX

4 Appendix

4.1 PlainDoc tags

4.1.1 Design variables

It is sometime useful to include design variables in the design documentation.

Design variables are included using the command

<<desvar:testbench1/script.ocn>>

The command extracts lines containing

desVar("variable" Value); Comment

and creates a table

Table 2:

Variable Value commentVsupply 1.8 Supply voltagec1 100p Parasitic load

The variables are automatically extracted from an ocean script file. Only variabledefinitions printed at the beginning of a line will be included. This is in order toallow variables to be omitted from a table by simply adding a space in front of thevariable name.

4.1.2 Log files

Output log-files can be inserted using

<<logfile:filename.txt>>

The log file is formatted using typewriter type font. Long lines are broken in orderto not overflow the paper.


EDDA 4 APPENDIX

4.1.3 Schematics

Schematics are included using

<<sch:Schematic (Library)>>

where Schematic is the name of the schematic and Library is the library name.You currently have to specify the name of each schematic and library manually.

Schematics should be printed using hierarchical print from cadence to the direc-tory sch in the documentation directory. Plot the schematics without header andremember the last / when specifying the plot path.

4.1.4 Images

Figures and images are inserted using the command

<<img:image, position, size:Caption>>

where image is the name of the image without suffix specifying file type. .eps,.png, and .jpg images are recognised automatically.

The optional position and size are used to control the position and size of theimage in the PDF output. Please consult the PlainDoc documentation for details.

Caption is the caption of the image.

Images can be referenced using the image name.

Currently all images have to be located in the documentation directory, includingimages fron sub-directories do not work.

Example:

<<img:hotdogs.jpg,,3:Hot dogs>>

includes the file hotdogs.jpg from the documentation directory.

The size "3" makes the image fill 1/3 of the page width in the PDF document.


EDDA 4 APPENDIX

Figure 5: Hot dogs

4.1.5 Tables

Tables are inserted using the table command:

<<table:Example tableTitle1 Title2======= ======Text Value>>

Will insert a table:

Table 3: Example table

Title1 Title2Text Value

4.1.6 Equations

Equations are inserted using the eqn tag.

Syntax:

<<eqn:equation:tag>>

equation is the equation definition using TeX syntax. There are numerous sourcesof information regarding TeX on the internet. one good starting point is

http://www.artofproblemsolving.com/LaTeX/AoPS_L_GuideCommands.php

tag is an optional tag in order to allow referencing of the equation.

Example:


EDDA 4 APPENDIX

<<eqn:f_0=\frac{1}{2\pi\sqrt{L(C_0+C_{ext})}}:f_res>>

Generates the equation

f0 =1

2π√

L(C0 +Cext)(2)

4.1.7 References

The see command is used to insert a reference

< <see : tag> >

The tag is replaced by the number of the figure, plot or table.

Referencing is done by name matching, where the tag that have the closest matchis used. If the match is not exact a warning is generated when generating thedocument but the reference is still valid.


EDDA 4 APPENDIX

4.2 Skill functions

The skill scripts are a collection of scripts to launch simulations and to log simu-lation results. These scripts are used as commands within an ocean script.

Table 4 lists the available skill scripts.

Table 4: Skill scripts

Script Description Referencesim Launch a simulation 4.2.1log_data Log data point 4.2.2log_wave Log waveform 4.2.3log_data_point Creates waveform from data points 4.2.4log_data_gap Creates a gap in a waveform 4.2.5

4.2.1 sim

Load simulation script and run simulation.

Syntax:

sim "ocean_script" "corner"

Example:

> sim "test.ocn" "slow"

The example above simulates the script test.ocn in corner slow.

> sim "test.ocn"

runs the simulation in the same corner as previous simulation. Default corner istyp.

> sim

repeats the simulation using previous script file and corner.


EDDA 4 APPENDIX

4.2.2 log_data

Log single value data point.

Syntax:

log_data( data "filename" )

Data will be saved in the folder corresponding to the current simulation corner.

Example:

log_data(IDC("/V0/PLUS") "Isupply")

4.2.3 log_wave

Log waveform data

Syntax:

log_wave( waveform "filename")

Save waveform data to a file named filename. Data will be saved in the foldercorresponding to the current simulation corner.

Example:

log_wave(VT("/Vout") "Vout")

4.2.4 log_data_point

Save numerical data-point to waveform file

Syntax:

log_data_point(xdata ydata "filename")

This function is useful in simulation loops, where each iteration creates a newdata-point.

Example:


EDDA 5 CHANGE LOG

foreach(vbias ’(0.8 0.9 1.0)desVar("Vbias" vbias)run()log_data_point(vbias value(dB20(VF("/out")),10M) "ACgain10M_vs_bias")

)

runs three simulations for vbias = 0.8, 0.9 and 1.0. A waveform ACgain10M_vs_biasis created.

4.2.5 log_data_gap

Lifts the pen in a waveform. Syntax:

log_data_gap(output)

This is useful if the plot should not be a continues line.

Example:

log_data_gap("ACgain10M_vs_bias")

4.3 Command line scripts

4.3.1 pddd

pddd is a pearl script to generate the HTML and PDF files from the PlainDocdocument.

pddd plaindoc.pd : Convert plaindoc.pd to PDF and HTMLpddd -init : Creates simulation directories

The pddd script is based on the PlainDoc system script pd2tex originally cre-ated by Sampo Kellomäki, but with several extensions and improvements. Themodifications was initially only intended for personal use, but as the project grewI decided to make the modifications public. Since documents created for pdddare not fully compatible with pd2tex I decided to make pddd a branch of thePlainDoc project.

The added features do currently not support DBX output.

5 Change log


EDDA 5 CHANGE LOG

Table 5: Change log

Date Description rev User2007-10-16

Image inclusion now possible from sub-directories 1.4 F Jonsson


Documents

1 Electronic Design Description Automation