EDDA. Fredrik Jonsson. December 7, Electronic Design Description Automation

Transcription

1 EDDA Fredrik Jonsson December 7, 2007 CVS revision Electronic Design Description Automation The EDDA documentation system is a collection of scripts created to simplify the process 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 simulations and log simulation results. 2. The PlainDoc script pddd (based on the pd2tex tool written by Sampo Kellomäki) to capture the simulation results into graphs and tables and create human readable design documentation (HTML and PDF documents). PlainDoc is a tool to convert text files having a to nicely formatted HTML and PDF documents. PlainDoc is powerfull enough to allows the user to create cross 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 compared to specification and inserted into the simulation document. This minimise the risk of human errors. Batch simulations over several corners can easily be simulated over night using scripts. 1

2 EDDA 1 ELECTRONIC DESIGN DESCRIPTION AUTOMATION Simple to update results. When a schematic is modified or model file is updated the simulation script can be relaunched and all new results are automatically inserted into the documents. Both HTML and PDF documents are automatically created for easy sharing of information within design group. This tutorial is written using PlainDoc by Fredrik Jonsson. You can view the source of this document here. If you have any comments or suggestions, please contact me at f jon@kth.se (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, and put the file edda/pddd in your executable search path. The EDDA system use a number of Unix tools like Perl, LaTeX and image magick when creating the documents. Most of these tools are standard on common Linux distributions. If the tools are not available they have to be downloaded and installed separately. EDDA have succesfully been tested on sevral different Redhat, Fedora and Cygwin 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 by Sampo Kellomäki. Information about PlainDoc can be found at EDDA is offered under the Gnu Public License (GPL). December 7, 2007 Fredrik Jonsson page 2

3 2 Using EDDA Below will follow a short overview how to run simulations and create design documentation using EDDA. In order to use the EDDA system it is assumed you are familiar with running Cadence simulations using Ocean. For information regarding how to configure these tools, please read the cadence documentation. To create a EDDA document from an existing Cadence simulation testbench we need to: 1. Create a documentation directory where the simulation files and documents will 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 and documents are created in a special directory structure. An example directory looks like figure 1 Figure 1: Directory structure The doc_directory is the documentation directory. This directory can have any name and location. The.pd directory stores temporary information when running PlainDoc. December 7, 2007 Fredrik Jonsson page 3

4 corners store files defining the different simulation corners. html will contain the HTML output Simulations scripts are stored in testbench directories. The testbench directory contains the netlist and the Ocean scripts. In the testbech directory a subdirectory for each simulation corner will be created containing simulation results. A documentation directory can contain any number of testbenches, but each testbench directory can only have one netlist. The tex directory contains temporary data when creating a PDF document using LaTeX. Finally edda.pd is the document source file. The generated HTML and PDF documents will have the same name as the source file. The directory structure can be generated using the command: > pddd -init December 7, 2007 Fredrik Jonsson page 4

5 2.2 OCEAN file When running a cadence within the Virtuoso analog design environment you can create an OCEAN script using the menu command Session->Save Script... In order to use the OCEAN script in the EDDA environment you need to modify the 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 compatible with EDDA. December 7, 2007 Fredrik Jonsson page 5

6 2.2.1 Corner file In order to use the script in the EDDA environment we first extract the corner definition. The corner definition files are located in the corners directory. The corner file can have any name, but the the name typ is reserved for the typical corner. 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 ) Create symbolic link The sim script will look for a link to the netlist in the test bench directory. When not 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 the cadence configuration and the user. The design definition must be removed from the 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 Remove simulator and directory information The sim script automatically configures the simulator and results directory so this information can be removed from the scripts file. Remove the lines December 7, 2007 Fredrik Jonsson page 6

7 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 store simulation results, where USER and SCRIPT will be replaced by the user name and name of the script file Log simulation results The EDDA system have a set of skill functions to log simulation results. Scalar data 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. A subdirectory for each corner will be generated. To log the DC voltage and the AC response in the example ocean script we can use 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/vdc and 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.ocn may 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") December 7, 2007 Fredrik Jonsson page 7

8 2.3 Running the simulation The simulation script are simulated using ocean. Start ocean within the testbench directory. > 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 specify another 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 the menu Simulation->Netlist->Recreate To rerun the simulation script using the previous script file and corner it is enough to type > sim A batch simulation simulating many corners can be created, for example by creating 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. December 7, 2007 Fredrik Jonsson page 8

9 2.4 Creating the simulation report The simulation results can be documented in a design document. The document is written in PlainDoc which is a simple text-file containing a few special "tags" to include simulation results, plots, equations, schematics etc Document structure In the document we first insert the document title: Example simulation ################## After this we insert information indicating the paper format, information about the author etc: <<class: article!a4paper,12pt>> <<author: Fredrik Jonsson>> Plain doc use a very simple yet powerful markup structure. Different headings are indicated by the way they are underlined: 1 Heading 1 =========== 1.1 Heading Heading 3 ~~~~~~~~~~~~~~~ The numbers at the beginning of the line are ignored when compiling the document, and sections are renumbered automatically. Lists is created by inserting a * or a number at the beginning of a line * Bulted list 1. Numbered list 2. Item 2 December 7, 2007 Fredrik Jonsson page 9

10 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 the output documents. For more detailed information about the PlainDoc syntax, please see the appendix or the PlainDoc documentation Inserting simulation results Simulation results are inserted using the tags data and plot. Scalar data is inserted into a table like table 1 Spec Result Parameter Min Typ Max Min Typ Max Unit Pass DC voltage slow f ast V using the data command: Table 1: Simulation result summary 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 following lines: <<data:simulation result summary:result1 dir=testbench1 Vdc,DC voltage,minmax,0.7,0.9,1.1,v,2 >> The first line <<data:simulation result summary:result1 December 7, 2007 Fredrik Jonsson page 10

11 specifies the beginning of a data section. The "Simulation result summary" is the caption 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 all directories 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. Currently only the spectype minmax is allowed. min, typ, max is the specification. Simulation results will be compared to these values, and if outside the limit the label "FAIL" will be written in the Pass column. 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 according to the unit prefix. If we for example specifies the unit to mv the simulated result will be multiplied by a factor 1000 before inserted into the table. Specification values are not scaled and should be specified in the correct unit, i.e. if the limit is 42mV we should use 42 in the specification. Precision specifies the numerical precision in the tabled. December 7, 2007 Fredrik Jonsson page 11

12 -5-10 ACmag:fast ACmag:slow ACmag:typ -15 gain [db] e+06 1e+07 1e+08 Frequency [Hz] Figure 2: AC gain 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 document a magnified version of the graph is presented. To plot the AC magnitude in the example simulation we use the following line: <<plot: set logscale x ACmag,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 December 7, 2007 Fredrik Jonsson page 12

13 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. Another useful 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 Gnuplot documentation at 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 the plot names. No space is allowed between the names. Specific simulation corners can be selected by putting the corner in parenthesis after the waveform name. The waveform caption can be specified by putting the caption within "". The corner is omitted from the caption if only simulation result from one corner is found. Example: The following example creates two plots. The first plot (Figure 3) have two 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 the slow corner. <<plot: set logscale x ACmag(typ slow)"mag"&acmag(fast)"gain fast",ac gain,freq,gain set logscale x set xrange [1e5:1e7] ACmag(slow)"Gain",AC gain,freq [Hz],gain [db] >> By default simulation data from all available corners and testbench directories are collected. You can specify a specific corner or directory by inserting dir and corners lines the same way as in the data table. If we only want the typ corner from testbench1 we can write: dir=testbench1 corners=typ December 7, 2007 Fredrik Jonsson page 13

14 -5-10 Mag:typ Mag:slow Gain fast gain e+06 1e+07 1e+08 Freq Figure 3: AC gain -6 Gain gain [db] e+06 1e+07 Freq [Hz] Figure 4: AC gain December 7, 2007 Fredrik Jonsson page 14

15 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 web browser. The PDF document is copied both to the HTML directory and to the documentation directory. 3 Example An example EDDA design description may look like this. The document is generated using the following source file. December 7, 2007 Fredrik Jonsson page 15

16 EDDA 4 APPENDIX 4 Appendix 4.1 PlainDoc tags 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 comment Vsupply 1.8 Supply voltage c1 100p Parasitic load The variables are automatically extracted from an ocean script file. Only variable definitions printed at the beginning of a line will be included. This is in order to allow variables to be omitted from a table by simply adding a space in front of the variable name 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 order to not overflow the paper. December 7, 2007 Fredrik Jonsson page 16

17 EDDA 4 APPENDIX 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 directory sch in the documentation directory. Plot the schematics without header and remember the last / when specifying the plot path 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 the image 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, including images 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. December 7, 2007 Fredrik Jonsson page 17

18 EDDA 4 APPENDIX Figure 5: Hot dogs Tables Tables are inserted using the table command: <<table:example table Title1 Title2 ======= ====== Text Value >> Will insert a table: Table 3: Example table Title1 Text Title2 Value Equations Equations are inserted using the eqn tag. Syntax: <<eqn:equation:tag>> equation is the equation definition using TeX syntax. There are numerous sources of information regarding TeX on the internet. one good starting point is tag is an optional tag in order to allow referencing of the equation. Example: December 7, 2007 Fredrik Jonsson page 18

19 EDDA 4 APPENDIX <<eqn:f_0=\frac{1}{2\pi\sqrt{l(c_0+c_{ext})}}:f_res>> Generates the equation 1 f 0 = 2π L(C 0 +C ext ) (2) 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 match is used. If the match is not exact a warning is generated when generating the document but the reference is still valid. December 7, 2007 Fredrik Jonsson page 19

20 EDDA 4 APPENDIX 4.2 Skill functions The skill scripts are a collection of scripts to launch simulations and to log simulation results. These scripts are used as commands within an ocean script. Table 4 lists the available skill scripts. Table 4: Skill scripts Script Description Reference sim Launch a simulation log_data Log data point log_wave Log waveform log_data_point Creates waveform from data points log_data_gap Creates a gap in a waveform 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 is typ. > sim repeats the simulation using previous script file and corner. December 7, 2007 Fredrik Jonsson page 20

21 EDDA 4 APPENDIX 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") log_wave Log waveform data Syntax: log_wave( waveform "filename") Save waveform data to a file named filename. Data will be saved in the folder corresponding to the current simulation corner. Example: log_wave(vt("/vout") "Vout") 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 new data-point. Example: December 7, 2007 Fredrik Jonsson page 21

22 EDDA 5 CHANGE LOG foreach(vbias ( ) 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_bias is created 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 pddd pddd is a pearl script to generate the HTML and PDF files from the PlainDoc document. pddd plaindoc.pd : Convert plaindoc.pd to PDF and HTML pddd -init : Creates simulation directories The pddd script is based on the PlainDoc system script pd2tex originally created by Sampo Kellomäki, but with several extensions and improvements. The modifications was initially only intended for personal use, but as the project grew I decided to make the modifications public. Since documents created for pddd are not fully compatible with pd2tex I decided to make pddd a branch of the PlainDoc project. The added features do currently not support DBX output. 5 Change log December 7, 2007 Fredrik Jonsson page 22

23 EDDA 5 CHANGE LOG Table 5: Change log Date Description rev User Image inclusion now possible from sub-directories 1.4 F Jonsson 16 December 7, 2007 Fredrik Jonsson page 23